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NAME 

intro - introduction to functions and libraries 
DESCRIPTION 

This section describes functions found in various libraries, 
other than those functions that directly invoke UNIX system 
primitives, which are described in Section 2 of this volume. 
Certain major collections are identified by a letter after the 
section number: 

(3C) These functions, together with those of Section 2 and 
those marked (3S), constitute the Standard C Library 
libc, which is automatically loaded by the C compiler, 
cc(1). (For this reason the (3C) and (3S) sections 
together comprise one section of this manual.) The link 
editor ld{1) searches this library under the -Ic option. A 
"shared library" version of libc can be searched using 
the -lc_s option, resulting in smaller a.outs. Declara- 
tions for some of these functions may be obtained from 
#include files indicated on the appropriate pages. 

(3S) These functions constitute the "standard I/O package" 
[see stdio{3S)]. These functions are in the library libc, 
already mentioned. Declarations for these functions 
may be obtained from the #include file <stdio.h>. 

(3M) These functions constitute the Math Library, libm. They 
are automatically loaded as needed by the FORTRAN 
compiler f77(1). They are not automatically loaded by 
the C compiler, cc(1); however, the link editor searches 
this library under the -Im option. Declarations for these 
functions may be obtained from the #include file 
< math.h > . Several generally useful mathematical con- 
stants are also defined there [see math (5)]. 

(3N) This contains sets of functions constituting the Network 
Services library. These sets provide protocol indepen- 
dent interfaces to networking services based on the ser- 
vice definitions of the OSI (Open Systems Interconnec- 
tion) reference model. Application developers access 
the function sets that provide services at a particular 
level. 

The function sets contained in the library are: 

TRANSPORT INTERFACE (TI) - provide the services 
of the OSI Transport Layer. These services provide 
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reliable end-to-end data transmission using the ser- 
vices of an underlying network. Applications writ- 
ten using the TI functions are independent of the 
underlying protocols. Declarations for these func- 
tions may be obtained from the #include file 
<tiuser.h>. The link editor /c/(1) searches this 
library under the -lnsl_s option. 
(3X) Various specialized libraries. The files in which these 

libraries are found are given on the appropriate pages. 
(3F) These functions constitute the FORTRAN intrinsic func- 
tion library, libF77. These functions are automatically 
available to the FORTRAN programmer and require no 
special invocation of the compiler. 

DEFINITIONS 

A character is any bit pattern able to fit into a byte on the 
machine. The null character is a character with value 0, 
represented in the C language as '\0'. A character array is a 
sequence of characters. A null-terminated character array is a 
sequence of characters, the last of which is the null character. 
A string is a designation for a null-terminated character array. 
The null string is a character array containing only the null 
character. A NULL pointer is the value that is obtained by 
casting 0 into a pointer. The C language guarantees that this 
value will not match that of any legitimate pointer, so many 
functions that return pointers return it to indicate an error. 
NULL is defined as 0 in <stdio.h>; the user can include an 
appropriate definition if not using < stdio.h > . 

Many groups of FORTRAN intrinsic functions have generic 
function names that do not require explicit or implicit type 
declaration. The type of the function will be determined by 
the type of its argument (s). For example, the generic function 
max will return an integer value if given integer arguments 
(maxO), a real value if given real arguments (amaxl), or a 
double-precision value if given double-precision arguments 
(dmaxl) . 

Netbuf In the Network Services library, netbuf is a structure 
used in various Transport Interface (TI) functions to send and 
receive data and information. It contains the following 
members: 
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unsigned int maxlen; 
unsigned int len; 
char *buf; 

Buf points to a user input and/or output buffer. Len generally 
specifies the number of bytes contained in the buffer. If the 
structure is used for both input and output, the function will 
replace the user value of len on return. 

Maxlen generally has significance only when buf is used to 
receive output from the TI function. In this case, it specifies 
the physical size of the buffer, the maximum value of len that 
can be set by the function. If maxlen is not large enough to 
hold the returned information, an TBUFOVFLW error will gen- 
erally result. However, certain functions may return part of 
the data and not generate an error. 

FILES 

LIBDIR usually /lib 
LIBDIR/libc.a 
LIBDIR/libc_s.a 
LIBDIR/libm.a 
LIBDIR/lib77.a 
/shlib/libcs 
/shlib/libnsl_s (3N) 
/usr/lib/libnsl_s.a (3N) 

SEE ALSO 

ar(1), cc(1), ld(1), lint(1), nm(1), intro(2), stdio(3S), math(5). 

DIAGNOSTICS 

Functions in the C and Math Libraries (3C and 3M) may return 
the conventional values 0 or ±HUGE (the largest-magnitude 
single-precision floating-point numbers; HUGE is defined in 
the <math.h> header file) when the function is undefined for 
the given arguments or when the value is not representable. 
In these cases, the external variable errno [see intro(2)] is set 
to the value EDOM or ERANGE. 

WARNING 

Many of the functions in the libraries call and/or refer to other 
functions and external variables described in this section and 
in Section 2 (System Calls). If a program inadvertently defines 
a function or external variable with the same name, the 
presumed library version of the function or external variable 
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may not be loaded. The //7?f(1) program checker reports name 
conflicts of this kind as "multiple declarations' * of the names in 
question. Definitions for Sections 2, 3C, and 3S are checked 
automatically. Other definitions can be included by using the -I 
option. (For example, -1m includes definitions for Section 3M, 
the Math library.) Use of lint is highly recommended. 



Page 4 



UP-13712 



A64L(3C) 



NAME 

a64l, 164a - convert between long integer and base-64 ASCII 
string 

SYNOPSIS 

long a64l (s) 
char *s; 

char *l64a (I) 
long I; 

DESCRIPTION 

These functions are used to maintain numbers stored in base- 
64 ASCII characters. This is a notation by which long integers 
can be represented by up to six characters; each character 
represents a "digit" in a radix-64 notation. 

The characters used to represent "digits" are . for 0, / for 1, 0 
through 9 for 2-11, A through Z for 12-37, and a through z for 
38-63. 

a64l takes a pointer to a null-terminated base-64 representa- 
tion and returns a corresponding long value. If the string 
pointed to by s contains more than six characters, a64l will 
use the first six. 

a64l scans the character string from left to right, decoding 
each character as a 6 bit Radix 64 number. 

164a takes a long argument and returns a pointer to the 
corresponding base-64 representation. If the argument is 0, 
164a returns a pointer to a null string. 

CAVEAT 

The value returned by 164a is a pointer into a static buffer, the 
contents of which are overwritten by each call. 
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NAME 

abort - generate an IOT fault 

SYNOPSIS 

int abort ( ) 

DESCRIPTION 

abort does the work of exit {2), but instead of just exiting, 
abort causes SIGABRT to be sent to the calling process. If 
SIGABRT is neither caught nor ignored, all stdio (3S) streams 
are flushed prior to the signal being sent, and a core dump 
results. 

abort returns the value of the kill(2) system call. 

SEE ALSO 

sdb(1), exit(2), kill (2), signal (2). 

DIAGNOSTICS 

If SIGABRT is neither caught nor ignored, and the current 
directory is writable, a core dump is produced and the mes- 
sage "abort - core dumped" is written by the shell. 
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NAME 

abs - return integer absolute value 

SYNOPSIS 
int abs (i) 
int i; 

DESCRIPTION 

abs returns the absolute value of its integer operand. 

SEE ALSO 

floor(3M). 

CAVEAT 

In two's-complement representation, the absolute value of the 
negative integer with largest magnitude is undefined. Some 
implementations trap this error, but others simply ignore it. 
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NAME 

bsearch - binary search a sorted table 

SYNOPSIS 

#include < search. h> 

char *bsearch ((char *) key, (char *) base, nel, sizeof 
(*key), compar) 
unsigned nel; 
int (*compar)( ); 

DESCRIPTION 

bsearch is a binary search routine generalized from Knuth 
(6.2.1) Algorithm B. It returns a pointer into a table indicating 
where a datum may be found. The table must be previously 
sorted in increasing order according to a provided comparison 
function. Key points to a datum instance to be sought in the 
table. Base points to the element at the base of the table. 
Nel is the number of elements in the table. Compar is the 
name of the comparison function, which is called with two 
arguments that point to the elements being compared. The 
function must return an integer less than, equal to, or greater 
than zero as accordingly the first argument is to be con- 
sidered less than, equal to, or greater than the second. 

EXAMPLE 

The example below searches a table containing pointers to 
nodes consisting of a string and its length. The table is 
ordered alphabetically on the string in the node pointed to by 
each entry. 

This code fragment reads in strings and either finds the 
corresponding node and prints out the string and its length, or 
prints an error message. 

^include <stdio.h> 
#indude <search.h> 

#define TABSIZE 1000 



struct node { 

char *string; 
int length; 

I; 

struct node table [TABSIZE]; 



/* these are stored in the table */ 



/* table to be searched */ 
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struct node *node_ptr, node; 

int node_compare( ); /* routine to compare 2 nodes */ 
char str_space[20]; /* space to read string into */ 



node. string = str_space; 

while (scanf ("%s", node. string) != EOF) \ 

node_ptr = (struct node *)bsearch( (char *)(&node), 
(char *)table, TABSIZE, 
sizeof (struct node), node_compare ) ; 
if (node_ptr != NULL) \ 

(void)printf ("string = %20s, length = %d\n", 
node_ptr->str ing, node_ptr->l ength ) ; 

I else I 

(void)printf ("not found: %s\n", node.string); 

I 

I 

I 

/* 

This routine compares two nodes based on an 
alphabetical ordering of the string field. 

*/ 

int 

node_compare(node1, node2) 
char *node1, *node2; 
I 

return (strcmp( 

((struct node *)node1 )->string, 
((struct node *)node2)->string) ); 

I 

NOTES 

The pointers to the key and the element at the base of the 
table should be of type pointer-to-element, and cast to type 
pointer-to-character. 

The comparison function need not compare every byte, so 
arbitrary data may be contained in the elements in addition to 
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the values being compared. 

Although bsearch is declared as type pointer-to-character, the 
value returned should be cast into type pointer-to-element. 

SEE ALSO 

hsearch(3C), lsearch(3C), qsort(3C), tsearch(3C). 

DIAGNOSTICS 

A NULL pointer is returned if the key cannot be found in the 
table. 
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NAME 

clock - report CPU time used 

SYNOPSIS 

long clock ( ) 

DESCRIPTION 

clock returns the amount of CPU time (in microseconds) used 
since the first call to clock. The time reported is the sum of 
the user and system times of the calling process and its ter- 
minated child processes for which it has executed wait (2), 
pclose (3S) , or system (3S) . 

SEE ALSO 

times(2), wait(2), popen(3S), system(3S). 

BUGS 

The value returned by clock is defined in microseconds for 
compatibility with systems that have CPU clocks with much 
higher resolution. Because of this, the value returned will 
wrap around after accumulating only 2147 seconds of CPU 
time (about 36 minutes). 
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NAME 

conv: toupper, tolower, _toupper, _tolower, toascii - translate 
characters 

SYNOPSIS 

#include <ctype.h> 

int toupper (c) 
int c; 

int tolower (c) 
int c; 

int toupper (c) 
int c; 

int tolower (c) 
int c; 

int toascii (c) 
int c; 

DESCRIPTION 

Toupper and tolower have as domain the range of getc (3S): 
the integers from -1 through 255. If the argument of toupper 
represents a lower-case letter, the result is the corresponding 
upper-case letter. If the argument of tolower represents an 
upper-case letter, the result is the corresponding lower-case 
letter. All other arguments in the domain are returned 
unchanged. 

The macros toupper and Jolower, are macros that accom- 
plish the same thing as toupper and tolower but have res- 
tricted domains and are faster. Joupper requires a lower- 
case letter as its argument; its result is the corresponding 
upper-case letter. The macro Jolower requires an upper-case 
letter as its argument; its result is the corresponding lower- 
case letter. Arguments outside the domain cause undefined 
results. 

Toascii yields its argument with all bits turned off that are not 
part of a standard ASCII character; it is intended for compati- 
bility with other systems. 

SEE ALSO 

ctype(3C), getc(3S). 
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NAME 

crypt, setkey, encrypt - generate hashing encryption 

SYNOPSIS 

char *crypt (key, salt) 
char *key, *salt; 

void setkey (key) 
char *key; 

void encrypt (block, ignored) 
char *block; 
int ignored; 

DESCRIPTION 

crypt is the password encryption function. It is based on a 
one way hashing encryption algorithm with variations intended 
(among other things) to frustrate use of hardware implementa- 
tions of a key search. 

Key is a user's typed password. Salt is a two-character string 
chosen from the set [a-zA-ZO-9./]; this string is used to per- 
turb the hashing algorithm in one of 4096 different ways, after 
which the password is used as the key to encrypt repeatedly a 
constant string. The returned value points to the encrypted 
password. The first two characters are the salt itself. 

The setkey and encrypt entries provide (rather primitive) 
access to the actual hashing algorithm. The argument of set- 
key is a character array of length 64 containing only the char- 
acters with numerical value 0 and 1. If this string is divided 
into groups of 8, the low-order bit in each group is ignored; 
this gives a 56-bit key which is set into the machine. This is 
the key that will be used with the hashing algorithm to encrypt 
the string block with the function encrypt. 

The argument to the encrypt entry is a character array of 
length 64 containing only the characters with numerical value 
0 and 1 . The argument array is modified in place to a similar 
array representing the bits of the argument after having been 
subjected to the hashing algorithm using the key set by set- 
key. Ignored is unused by encrypt but it must be present. 

SEE ALSO 

getpass(3C), passwd(4). 

login(1), passwd(1) in the User's Reference Manual. 
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CAVEAT 

The return value points to static data that are overwritten by 
each call. 
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NAME 

ctermid - generate file name for terminal 

SYNOPSIS 

#include <stdio.h> 
char *ctermid (s) 
char *s; 

DESCRIPTION 

ctermid generates the path name of the controlling terminal 
for the current process, and stores it in a string. 

If s is a NULL pointer, the string is stored in an internal static 
area, the contents of which are overwritten at the next call to 
ctermid, and the address of which is returned. Otherwise, s is 
assumed to point to a character array of at least L_ctermid 
elements; the path name is placed in this array and the value 
of s is returned. The constant L_ctermid is defined in the 
<stdio.h> header file. 

NOTES 

The difference between ctermid and ttyname (3C) is that 
ttyname must be handed a file descriptor and returns the 
actual name of the terminal associated with that file descrip- 
tor, while ctermid returns a string (/dev/tty) that will refer to 
the terminal if used as a file name. Thus ttyname is useful 
only if the process already has at least one file open to a ter- 
minal. 

SEE ALSO 

ttyname (3C). 
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NAME 

ctime, localtime, gmtime, asctime, tzset - convert date and 
time to string 

SYNOPSIS 

#include < sys/types.h > 
#include <time.h> 

char *ctime (clock) 
time t *clock; 

struct tm *localtime (clock) 
time t *clock; 

struct tm *gmtime (clock) 
time t *clock; 

char *asctime (tm) 
struct tm *tm; 

extern long timezone; 

extern int daylight; 

extern char *tzname[2]; 

void tzset ( ) 

DESCRIPTION 

ctime converts a long integer, pointed to by clock, represent- 
ing the time in seconds since 00:00:00 GMT, January 1, 1970, 
and returns a pointer to a 26-character string in the following 
form. All the fields have constant width. 

Sun Sep 16 01:03:52 1985\n\0 

Localtime and gmtime return pointers to "tm" structures, 
described below. Localtime corrects for the time zone and 
possible Daylight Savings Time; gmtime converts directly to 
Greenwich Mean Time (GMT), which is the time the UNIX sys- 
tem uses. 

Asctime converts a "tm" structure to a 26-character string, as 
shown in the above example, and returns a pointer to the 
string. 

Declarations of all the functions and externals, and the "tm" 
structure, are in the <time.h> header file. The structure 
declaration is: 
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struct tm { 

int tm_sec; /* seconds (0 - 59) */ 

int tmjnin; /* minutes (0 - 59) */ 

int tmjiour; /* hours (0 - 23) */ 

int tmjmday; /* day of month (1 - 31) */ 

int tmjnon; /* month of year (0 - 11) */ 

int tm_year; /* year - 1900 */ 

int tm wday; /* day of week (Sunday = 0) */ 

int tm_yday; /* day of year (0 - 365) */ 

int tmjsdst; 

}; 

Tmjsdst is non-zero if Daylight Savings Time is in effect. 

The external long variable timezone contains the difference, in 
seconds, between GMT and local standard time (in EST, 
timezone is 5*60*60); the external variable daylight is non-zero 
if and only if the standard U.S.A. Daylight Savings Time 
conversion should be applied. The program knows about the 
peculiarities of this conversion in 1974 and 1975; if necessary, 
a table for these years can be extended. 

If an environment variable named TZ is present, asctime uses 
the contents of the variable to override the default time zone. 
The value of TZ must be a three-letter time zone name, fol- 
lowed by a number representing the difference between local 
time and Greenwich Mean Time in hours, followed by an 
optional three-letter name for a daylight time zone. For exam- 
ple, the setting for New Jersey would be EST5EDT. The 
effects of setting TZ are thus to change the values of the 
external variables timezone and daylight; in addition, the time 
zone names contained in the external variable 

char *tzname[2] = { "EST", "EDT" }; 

are set from the environment variable TZ. The function tzset 
sets these external variables from TZ; fzsef is called by asc- 
time and may also be called explicitly by the user. 

Note that in most installations, TZ is set by default when the 
user logs on, to a value in the local /etc/profile file [see pro- 
file (4)]. 

SEE ALSO 

time(2), getenv(3C), profile(4), environ(5). 
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CAVEAT 

The return values point to static data whose content is 
overwritten by each call. 
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NAME 

ctype: isalpha, isupper, islower, isdigit, isxdigit, isalnum, 
isspace, ispunct, isprint, isgraph, iscntrl, isascii - classify char- 
acters 

SYNOPSIS 

#include < ctype. h> 

int isalpha (c) 
int c: 



DESCRIPTION 

These macros classify character-coded integer values by table 
lookup. Each is a predicate returning nonzero for true, zero 
for false. Isascii is defined on all integer values; the rest are 
defined only where isascii is true and on the single non-ASCII 
value EOF [-1; see stdio {3S)]. 

isalpha c is a letter. 

isupper c is an upper-case letter. 

islower c is a lower-case letter. 

isdigit c is a digit [0-9]. 

isxdigit c is a hexadecimal digit [0-9], [A-F] or [a-f]. 

isalnum c is an alphanumeric (letter or digit). 

isspace c is a space, tab, carriage return, newline, 

vertical tab, or form-feed. 

ispunct c is a punctuation character (neither control 

nor alphanumeric). 

isprint c is a printing character, code 040 (space) 

through 0176 (tilde). 

isgraph c is a printing character, like isprint except 

false for space. 

iscntrl c is a delete character (0177) or an ordinary 

control character (less than 040). 

isascii c is an ASCII character, code less than 0200. 

SEE ALSO 

stdio(3S), ascii(5). 



UP-13712 



Page 1 



CTYPE(3C) 



DIAGNOSTICS 

If the argument to any of these macros is not in the domain of 
the function, the result is undefined. 
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NAME 

cuserid - get character login name of the user 

SYNOPSIS 

#include <stdio.h> 

char *cuserid (s) 
char *s; 

DESCRIPTION 

cuserid generates a character-string representation of the 
login name that the owner of the current process is logged in 
under. If s is a NULL pointer, this representation is generated 
in an internal static area, the address of which is returned. 
Otherwise, s is assumed to point to an array of at least 
L cuserid characters; the representation is left in this array. 
The constant L_cuserid is defined in the <stdio.h> header 
file. 

DIAGNOSTICS 

If the login name cannot be found, cuserid returns a NULL 
pointer; if s is not a NULL pointer, a null character (\0) will be 
placed at s[0], 

SEE ALSO 

getlogin(3C), getpwent(3C). 



UP-13712 



Page 1 



CUSERII)(3S) 



[This page left blank.] 



Page 2 



UP-13712 



DIAL(3C) 



NAME 

dial - establish an out-going terminal line connection 

SYNOPSIS 

#include <dial.h> 

int dial (call) 
CALL call; 

void undial (fd) 
int fd; 

DESCRIPTION 

dial returns a file-descriptor for a terminal line open for 
read/write. The argument to dial is a CALL structure (defined 
in the <dial.h> header file). 

When finished with the terminal line, the calling program must 
invoke undial to release the semaphore that has been set dur- 
ing the allocation of the terminal device. 

The definition of CALL in the <dial.h> header file is: 
typedef struct \ 



struct termio *attr; 


/* 


pointer to termio attribute 








struct */ 


int 


baud; 


/* 


transmission data rate */ 


int 


speed; 


/* 


212A modem: low=300, 








high=1200 */ 


char 


*line; 


/* 


device name for out- going 








line */ 


char 


*telno; 


/* 


pointer to tel-no digits 








string */ 


int 


modem; 


/* 


specify modem control for 








direct lines */ 


char 


*device; 


/* 


Will hold the name of the 








device used to make a 








connection */ 


int 


devjen; 


/* 


The length of the device 



used to make connection */ 

1 CALL; 

The CALL element speed is intended only for use with an out- 
going dialed call, in which case its value should be either 300 
or 1200 to identify the 113A modem, or the high- or low-speed 
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setting on the 21 2A modem. Note that the 113A modem or 
the low-speed setting of the 21 2A modem will transmit at any 
rate between 0 and 300 bits per second. However, the high- 
speed setting of the 21 2A modem transmits and receives at 
1200 bits per secound only. The CALL element baud is for the 
desired transmission baud rate. For example, one might set 
baud to 110 and speed to 300 (or 1200). However, if speed 
set to 1200 baud must be set to high (1200). 

If the desired terminal line is a direct line, a string pointer to its 
device-name should be placed in the line element in the CALL 
structure. Legal values for such terminal device names are 
kept in the L-devices file. In this case, the value of the baud 
element need not be specified as it will be determined from 
the L-devices file. 

The telno element is for a pointer to a character string 
representing the telephone number to be dialed. Such 
numbers may consist only of symbols described on the 
acu{7). The termination symbol will be supplied by the dial 
function, and should not be included in the telno string 
passed to dial in the CALL structure. 

The CALL element modem is used to specify modem control 
for direct lines. This element should be non-zero if modem 
control is required. The CALL element attr is a pointer to a 
termio structure, as defined in the termio.h header file. A 
NULL value for this pointer element may be passed to the dial 
function, but if such a structure is included, the elements 
specified in it will be set for the outgoing terminal line before 
the connection is established. This is often important for cer- 
tain attributes such as parity and baud-rate. 

The CALL element device is used to hold the device name 
(cul..) that establishes the connection. 

The CALL element devjen is the length of the device name 
that is copied into the array device. 

FILES 

/usr/lib/uucp/L-devices 
/usr/spool/uucp/LCK. .tty-device 

SEE ALSO 

alarm (2), read (2), write(2). 

acu(7), termio(7) in the System Administrator's Reference 
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Manual. 

uucp(lC) in the User's Reference Manual. 

DIAGNOSTICS 

On failure, a negative value indicating the reason for the 
failure will be returned. Mnemonics for these negative indices 
as listed here are defined in the <dial.h> header file. 



1 MTDDT 

1 N 1 Kr 1 


i 


/* 


interrupt occurred */ 


D_HUNG 


-2 


/* 


dialer hung (no return from 








write) */ 


NO_ANS 


-3 


/* 


no answer within 10 seconds */ 


I LL_BD 


-H 


/* 


illegal baud- rate */ 


A_PROB 


-5 


/* 


acu problem (open() failure) */ 


L_PROB 


-6 


/* 


line problem (open() failure) */ 


NO_LdV 


-7 


/* can't open LDEVS file */ 


DV_NT_A 


-8 


/* 


requested device not available * 


DV_NT_K 


-9 


/* 


requested device not known */ 


NO_BD_A 


-10 


/* 


no device available at 








requested baud */ 


NO_BD_K 


-11 


/* 


no device known at requested 



baud */ 

WARNINGS 

The dial (3C) library function is not compatible with Basic Net- 
working Utilities on UNIX System V Release 2.0. 

Including the <dial.h> header file automatically includes the 
<termio.h> header file. 

The above routine uses <stdio.h>, which causes it to 
increase the size of programs, not otherwise using standard 
I/O, more than might be expected. 

BUGS 

An alarm (2) system call for 3600 seconds is made (and 
caught) within the dial module for the purpose of "touching" 
the LCK.. file and constitutes the device allocation semaphore 
for the terminal device. Otherwise, uucp (1C) may simply 
delete the LCK.. entry on its 90-minute clean-up rounds. The 
alarm may go off while the user program is in a read (2) or 
write (2) system call, causing an apparent error return. If the 
user program expects to be around for an hour or more, error 
returns from reads should be checked for (errno= =EINTR), 
and the read possibly reissued. 
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NAME 

drand48, erand48, Irand48, nrand48, mrand48, jrand48, srand48, 
seed48, lcong48 generate uniformly distributed pseudo-random 
numbers 

SYNOPSIS 

double drand48 ( ) 

double erand48 (xsubi) 
unsigned short xsubi [3]; 

long Irand48 ( ) 

long nrand48 (xsubi) 
unsigned short xsubi [3]; 

long mrand48 ( ) 

long jrand48 (xsubi) 
unsigned short xsubi [3]; 

void srand48 (seedval) 
long seedval; 

unsigned short *seed48 (seed16v) 
unsigned short seed16v[3]; 

void lcong48 (param) 
unsigned short param [7]; 

DESCRIPTION 

This family of functions generates pseudo-random numbers using 
the well-known linear congruential algorithm and 48-bit integer 
arithmetic. 

Functions drand48 and erand48 return non-negative double- 
precision floating-point values uniformly distributed over the 
interval [0.0, 1 .0). 

Functions Irand48 and nrand48 return non-negative long integers 
uniformly distributed over the interval [0, 2 31 ). 

Functions mrand48 and jrand48 return signed long integers 
uniformly distributed over the interval [-2 31 , 2 31 ). 
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Functions srand48, seed48 and lcong48 are initialization entry 
points, one of which should be invoked before either drand48, 
Irand48 or mrand48 is called. (Although it is not recommended 
practice, constant default initializer values will be supplied 
automatically if drand48, Irand48 or mrand48 is called without a 
prior call to an initialization entry point.) Functions erand48, 
nrand48 and jrand48 do not require an initialization entry point to 
be called first. 

All the routines work by generating a sequence of 48-bit integer 
values, X„ according to the linear congruential formula 

X n+1 = (aX n + c) mod m n^O. 

The parameter m = 2 48 ; hence 48-bit integer arithmetic is 
performed. Unless lcong48 has been invoked, the multiplier value 
a and the addend value c are given by 

a = 5DEECE66D 16 = 2736731 631 55 8 
c = B-|6 = 1 3q. 

The value returned by any of the functions drand48, erand48, 
\rand48, nrand48, mrand48 or jrand48 is computed by first 
generating the next 48-bit Xj in the sequence. Then the 
appropriate number of bits, according to the type of data item to 
be returned, are copied from the high-order (leftmost) bits of Xj 
and transformed into the returned value. 

The functions drand48, Irand48 and mrand48 store the last 48-bit 
Xj generated in an internal buffer, and must be initialized prior to 
being invoked. The functions erand48, nrand48 and jrand48 
require the calling program to provide storage for the successive 
Xj values in the array specified as an argument when the 
functions are invoked. These routines do not have to be 
initialized; the calling program must place the desired initial value 
of Xj into the array and pass it as an argument. By using different 
arguments, functions erand48, nrand48 and jrand48 allow 
separate modules of a large program to generate several 
independent streams of pseudo-random numbers, i.e., the 
sequence of numbers in each stream will not depend upon how 
many times the routines have been called to generate numbers 
for the other streams. 
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The initializer function srand48 sets the high-order 32 bits of Xj 
to the 32 bits contained in its argument. The low-order 16 bits 
of Xj are set to the arbitrary value 330E 16 

The initializer function seed48 sets the value of X f to the 48-bit 
value specified in the argument array. In addition, the previous 
value of Xj is copied into a 48-bit internal buffer, used only by 
seed48, and a pointer to this buffer is the value returned by 
seed48. This returned pointer, which can just be ignored if not 
needed, is useful if a program is to be restarted from a given 
point at some future time use the pointer to get at and store the 
last Xj value, and then use this value to reinitialize via seed48 
when the program is restarted. 

The initialization function lcong48 allows the user to specify the 
initial Xj, the multiplier value a, and the addend value c. 
Argument array elements param[0-2] specify Xj, param[3-5] 
specify the multiplier a, and param[6] specifies the 16-bit addend 
c. After lcong48 has been called, a subsequent call to either 
srand48 or seed48 will restore the "standard" multiplier and 
addend values, a and c, and specified on the previous page. 

NOTES 

The source code for the portable version can be used on 
computers which do not have floating-point arithmetic. In such a 
situation, functions drand48 and erand48 are replaced by the two 
new functions below. 

long irand48 (m) 
unsigned short m; 

long krand48 (xsubi, m) 
unsigned short xsubi[3], m; 

Functions irand48 and krand48 return non-negative long integers 
uniformly distributed over the interval [0, m - 1]. 

SEE ALSO 

rand(3C). 
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NAME 

dup2 - duplicate an open file descriptor 

SYNOPSIS 

int dup2 (tildes, fildes2) 
int fildes, fildes2; 

DESCRIPTION 

Fildes is a file descriptor referring to an open file, and fildes2 
is a non-negative integer less than NOFILES. dup2 causes 
fildes2 to refer to the same file as fildes. If fildes2 already 
referred to an open file, it is closed first. 

dup2 will fail if one or more of the following are true: 

[EBADF] Fildes is not a valid open file descriptor. 

[EMFILE] NOFILES file descriptors are currently open. 

SEE ALSO 

creat(2), close(2), exec(2), fcntl(2), open(2), pipe(2), lockf(3C). 

DIAGNOSTICS 

Upon successful completion a non-negative integer, namely 
the file descriptor, is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 



UP-13712 



Page 1 



DUP2(3C) 



[This page left blank.] 



Page 2 



UP-13712 



ECVT(3C) 



NAME 

ecvt, fcvt, gcvt - convert floating-point number to string 

SYNOPSIS 

char *ecvt (value, ndigit, decpt, sign) 

double value; 

int ndigit, *decpt, *sign; 

char *fcvt (value, ndigit, decpt, sign) 

double value; 

int ndigit, *decpt, *sign; 

char *gcvt (value, ndigit, buf) 
double value; 
int ndigit; 
char *buf; 

DESCRIPTION 

ecvt converts value to a null-terminated string of ndigit digits 
and returns a pointer thereto. The high-order digit is non- 
zero, unless the value is zero. The low-order digit is rounded. 
The position of the decimal point relative to the beginning of 
the string is stored indirectly through decpt (negative means 
to the left of the returned digits). The decimal point is not 
included in the returned string. If the sign of the result is 
negative, the word pointed to by sign is non-zero, otherwise it 
is zero. 

Fcvt is identical to ecvt, except that the correct digit has been 
rounded for printf "%f" (FORTRAN F-format) output of the 
number of digits specified by ndigit. 

Gcvt converts the value to a null-terminated string in the array 
pointed to by buf and returns buf. It attempts to produce ndi- 
git significant digits in FORTRAN F-format if possible, other- 
wise E-format, ready for printing. A minus sign, if there is one, 
or a decimal point will be included as part of the returned 
string. Trailing zeros are suppressed. 

SEE ALSO 

printf (3S). 

BUGS 

The values returned by ecvt and fcvt point to a single static 
data array whose content is overwritten by each call. 
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NAME 

end, etext, edata - last locations in program 

SYNOPSIS 
extern end; 
extern etext; 
extern edata; 

DESCRIPTION 

These names refer neither to routines nor to locations with 
interesting contents. The address of etext is the first address 
above the program text, edata above the initialized data 
region, and end above the uninitialized data region. 

When execution begins, the program break (the first location 
beyond the data) coincides with end, but the program break 
may be reset by the routines of brk{2), malloc (3C), standard 
input/output [sfoVo (3S)], the profile (-p) option of cc(1), and 
so on. Thus, the current value of the program break should 
be determined by sbrk (char *)(0) [see brk{2)]. 

SEE ALSO 

cc(1), brk(2), malloc(3C), stdio(3S). 



UP-13712 



Page 1 



END(3C) 



[This page left blank.] 



Page 2 



UP-13712 



FCLOSE (3S) 



NAME 

fclose, fflush - close or flush a stream 

SYNOPSIS 

#include <stdio.h> 

int fclose (stream) 
FILE *stream; 

int fflush (stream) 
FILE *stream; 

DESCRIPTION 

fclose causes any buffered data for the named stream to be 
written out, and the stream to be closed. 

fclose is performed automatically for all open files upon calling 
exit (2). 

Fflush causes any buffered data for the named stream to be 
written to that file. The stream remains open. 

SEE ALSO 

close(2), exit(2), fopen(3S), setbuf(3S), stdio(3S). 

DIAGNOSTICS 

These functions return 0 for success, and EOF if any error 
(such as trying to write to a file that has not been opened for 
writing) was detected. 
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NAME 

terror, feof, clearerr, fileno - stream status inquiries 

SYNOPSIS 

#include <stdio.h> 

int ferror (stream) 
FILE *stream; 

int feof (stream) 
FILE * stream; 

void clearerr (stream) 
FILE *stream; 

int fileno (stream) 
FILE *stream; 

DESCRIPTION 

ferror returns non-zero when an I/O error has previously 
occurred reading from or writing to the named stream, other- 
wise zero. 

Feof returns non-zero when EOF has previously been 
detected reading the named input stream, otherwise zero. 

Clearerr resets the error indicator and EOF indicator to zero 
on the named stream. 

Fileno returns the integer file descriptor associated with the 
named stream ; see open (2) . 

NOTES 

All these functions are implemented as macros; they cannot 
be declared or redeclared. 

SEE ALSO 

open (2), fopen(3S), stdio(3S). 
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NAME 

fopen, freopen, fdopen - open a stream 

SYNOPSIS 

#include <stdio.h> 

FILE *fopen (filename, type) 
char ^filename, *type; 

FILE *freopen (filename, type, stream) 
char "filename, *type; 
FILE *stream; 

FILE *fdopen (fildes, type) 
int fildes; 
char *type; 

DESCRIPTION 

fopen opens the file named by filename and associates a 
stream with it. fopen returns a pointer to the FILE structure 
associated with the stream. 

Filename points to a character string that contains the name 
of the file to be opened. 

Type is a character string having one of the following values: 

"r" open for reading 

"w" truncate or create for writing 

"a" append; open for writing at end of file, or 

create for writing 

"r + " open for update (reading and writing) 

"w + " truncate or create for update 

"a + " append; open or create for update at end-of- 
file 

Freopen substitutes the named file in place of the open 
stream. The original stream is closed, regardless of whether 
the open ultimately succeeds. Freopen returns a pointer to 
the FILE structure associated with stream. 

Freopen is typically used to attach the preopened streams 
associated with stdin, stdout and stderr to other files. 

Fdopen associates a stream with a file descriptor. File 
descriptors are obtained from open, dup, creat, or pipe (2), 
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which open files but do not return pointers to a FILE structure 
stream. Streams are necessary input for many of the Section 
3S library routines. The type of stream must agree with the 
mode of the open file. 

When a file is opened for update, both input and output may 
be done on the resulting stream. However, output may not 
be directly followed by input without an intervening fseek or 
rewind, and input may not be directly followed by output 
without an intervening fseek, rewind, or an input operation 
which encounters end-of-file. 

When a file is opened for append (i.e., when type is "a" or 
"a + "), it is impossible to overwrite information already in the 
file. Fseek may be used to reposition the file pointer to any 
position in the file, but when output is written to the file, the 
current file pointer is disregarded. All output is written at the 
end of the file and causes the file pointer to be repositioned at 
the end of the output. If two separate processes open the 
same file for append, each process may write freely to the file 
without fear of destroying output being written by the other. 
The output from the two processes will be intermixed in the 
file in the order in which it is written. 

SEE ALSO 

creat(2), dup(2), open(2), pipe(2), fclose(3S), fseek(3S), 
stdio(3S). 

DIAGNOSTICS 

fopen, fdopen, and f reopen return a NULL pointer on failure. 
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NAME 

fpgetround, fpsetround, fpgetmask, fpsetmask, fpgetsticky, 
fpsetsticky - IEEE floating point environment control 

SYNOPSIS 

//include <ieeefp.h> 

typedef enum 
I 

FP_RN=0, /* round to nearest */ 
FP_RP, /* round to plus */ 
FP_RM, /* round to minus */ 
FP_RZ, /* round to zero (truncate) */ 
] fp_rnd; 

f p_rnd f pgetround ( ) ; 

fp_rnd fpsetround (rnd_dir ) 
fp_rnd rnd_dir; 

//define fp_except int 
//define FP_X_INV 0x10 

//define FP_X_0FL 0x08 

//define FP_X_UFL 0x04 

//define FP_X_DZ 0x02 

//define FP_X_IMP 0x01 



fp_except fpgetmask(); 

fp_except fpsetmask (mask); 
fp_except mask; 

fp_except fpgetsticky( ); 

fp_except fpsetsticky (sticky); 
fp_except sticky; 

DESCRIPTION 

There are five floating point exceptions: divide-by-zero, over- 
flow, underflow, imprecise (inexact) result, and invalid opera- 
tion. When a floating point exception occurs, the 



/* invalid operation 

exception*/ 
/* overflow exception*/ 
/* underflow exception*/ 
/* divide- by- zero exception*/ 
/* imprecise (loss of 
precision)*/ 
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corresponding sticky bit is set (1), and if the mask bit is 
enabled (1), the trap takes place. These routines let the user 
change the behavior on occurrence of any of these excep- 
tions, as well as change the rounding mode for floating point 
operations. 

fpgetroundf) returns the current rounding mode. 

fpsetroundi) sets the rounding mode and returns the previous 
rounding mode. 

fpgetmaskQ returns the current exception masks. 

fpsetmaskty sets the exception masks and returns the previ- 
ous setting. 

fpgetstickyQ returns the current exception sticky flags. 

fpsetstickyQ sets (clears) the exception sticky flags and 
returns the previous setting. 

SEE ALSO 

isnan(3C). 

WARNINGS 

fpsetstickyf) modifies all sticky flags, fpsetmaskf) changes all 
mask bits. 

Both C and F77 require truncation (round to zero) for floating 
point to integral conversions. The current rounding mode has 
no effect on these conversions. 

CAVEATS 

One must clear the sticky bit to recover from the trap and to 
proceed. If the sticky bit is not cleared before the next trap 
occurs, a wrong exception type may be signaled. 

For the same reason, when calling fpsetmaskQ the user should 
make sure that the sticky bit corresponding to the exception 
being enabled is cleared. 
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NAME 

f read, fwrite - binary input/output 

SYNOPSIS 

#include <stdio.h> 
^include < sys/types.h > 

int fread (ptr, size, nitems, stream) 
char *ptr; 
int nitems; 
sizet size; 
FILE *stream; 

int fwrite (ptr, size, nitems, stream) 
char *ptr; 
int nitems; 
size t size; 
FILE *stream; 

DESCRIPTION 

fread copies, into an array pointed to by ptr, nitems items of 
data from the named input stream, where an item of data is a 
sequence of bytes (not necessarily terminated by a null byte) 
of length size, fread stops appending bytes if an end-of-file 
or error condition is encountered while reading stream, or if 
nitems items have been read, fread leaves the file pointer in 
stream, if defined, pointing to the byte following the last byte 
read if there is one. fread does not change the contents of 
stream . 

fwrite appends at most nitems items of data from the array 
pointed to by ptr to the named output stream, fwrite stops 
appending when it has appended nitems items of data or if an 
error condition is encountered on stream, fwrite does not 
change the contents of the array pointed to by ptr. 

The argument size is typically sizeof(*ptr) where the pseudo- 
function sizeof specifies the length of an item pointed to by 
ptr. If ptr points to a data type other than char it should be 
cast into a pointer to char. 

SEE ALSO 

read(2), write (2), fopen(3S), getc(3S), gets(3S), printf(3S), 
putc(3S), puts(3S), scanf(3S), stdio(3S). 
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DIAGNOSTICS 

fread and fwrite return the number of items read or written. If 
nitems is non-positive, no characters are read or written and 0 
is returned by both fread and fwrite. 
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NAME 

frexp, Idexp, modf - manipulate parts of floating-point 
numbers 

SYNOPSIS 

double frexp (value, eptr) 
double value; 
int *eptr; 

double Idexp (value, exp) 
double value; 
int exp; 

double modf (value, iptr) 
double value, *iptr; 

DESCRIPTION 

Every non-zero number can be written uniquely as x* 2 n , 
where the "mantissa" (fraction) x is in the range 0.5 < = \x\ 
< 1.0, and the "exponent" n is an integer, frexp returns the 
mantissa of a double value, and stores the exponent indirectly 
in the location pointed to by eptr. If value is zero, both results 
returned by frexp are zero. 

Ldexp returns the quantity value * 2 ex P. 

Modf returns the signed fractional part of value and stores the 
integral part indirectly in the location pointed to by iptr. 

DIAGNOSTICS 

If Idexp would cause overflow, ±HUGE (defined in 
<math.h> ) is returned (according to the sign of value), and 
errno is set to ERANGE. 

If Idexp would cause underflow, zero is returned and errno is 
set to ERANGE. 
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NAME 

fseek, rewind, ftell - reposition a file pointer in a stream 

SYNOPSIS 

#include <stdio.h> 

int fseek (stream, offset, ptrname) 
FILE *stream; 
long offset; 
int ptrname; 

void rewind (stream) 
FILE * st ream; 

long ftell (stream) 
FILE *stream; 

DESCRIPTION 

fseek sets the position of the next input or output operation 
on the stream. The new position is at the signed distance 
offset bytes from the beginning, from the current position, or 
from the end of the file, according as ptrname has the value 0, 
1, or 2. 

Rewind (stream) is equivalent to fseek (stream, 0L, 0), except 
that no value is returned. 

fseek and rewind undo any effects of ungetc (3S). 

After fseek or rewind, the next operation on a file opened for 
update may be either input or output. 

Ftell returns the offset of the current byte relative to the 
beginning of the file associated with the named stream. 

SEE ALSO 

lseek(2), fopen(3S), popen(3S), stdio(3S), ungetc(3S). 

DIAGNOSTICS 

fseek returns non-zero for improper seeks, otherwise zero. An 
improper seek can be, for example, an fseek done on a file 
that has not been opened via fopen; in particular, fseek may 
not be used on a terminal, or on a file opened via popen (3S). 

WARNING 

Although on the UNIX system an offset returned by ftell is 
measured in bytes, and it is permissible to seek to positions 
relative to that offset, portability to non-UNIX systems requires 
that an offset be used by fseek directly. Arithmetic may not 
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meaningfully be performed on such an offset, which is not 
necessarily measured in bytes. 
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NAME 

ftw - walk a file tree 

SYNOPSIS 

#include <ftw.h> 

int ftw (path, fn, depth) 
char *path; 
int (*fn) ( ); 
int depth; 

DESCRIPTION 

ftw recursively descends the directory hierarchy rooted in 
path. For each object in the hierarchy, ftw calls fn, passing it 
a pointer to a null-terminated character string containing the 
name of the object, a pointer to a stat structure [see stat(2)] 
containing information about the object, and an integer. Pos- 
sible values of the integer, defined in the <ftw.h> header file, 
are FTW F for a file, FTW D for a directory, FTW_DNR for a 
directory that cannot be read, and FTW_NS for an object for 
which stat could not successfully be executed. If the integer 
is FTW_DNR, descendants of that directory will not be pro- 
cessed. If the integer is FTW_NS, the stat structure will con- 
tain garbage. An example of an object that would cause 
FTW_NS to be passed to fn would be a file in a directory with 
read but without execute (search) permission. 

ftw visits a directory before visiting any of its descendants. 

The tree traversal continues until the tree is exhausted, an 
invocation of fn returns a nonzero value, or some error is 
detected within ftw (such as an I/O error). If the tree is 
exhausted, ftw returns zero. If fn returns a nonzero value, ftw 
stops its tree traversal and returns whatever value was 
returned by fn. If ftw detects an error, it returns -1, and sets 
the error type in errno. 

ftw uses one file descriptor for each level in the tree. The 
depth argument limits the number of file descriptors so used. 
If depth is zero or negative, the effect is the same as if it were 
1. Depth must not be greater than the number of file descrip- 
tors currently available for use. ftw will run more quickly if 
depth is at least as large as the number of levels in the tree. 

SEE ALSO 

stat(2), malloc(3C). 
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BUGS 

Because ftw is recursive, it is possible for it to terminate with a 
memory fault when applied to very deep file structures. 

CAVEAT 

ftw uses malloc (3C) to allocate dynamic storage during its 
operation. If ftw is forcibly terminated, such as by longjmp 
being executed by fn or an interrupt routine, ftw will not have 
a chance to free that storage, so it will remain permanently 
allocated. A safe way to handle interrupts is to store the fact 
that an interrupt has occurred, and arrange to have fn return 
a nonzero value at its next invocation. 



Page 2 



UP-13712 



GETC(3S) 



NAME 

getc, getchar, fgetc, getw - get character or word from a 
stream 

SYNOPSIS 

#include <stdio.h> 

int getc (stream) 
FILE *stream; 

int getchar () 

int fgetc (stream) 
FILE *stream; 

int getw (stream) 
FILE *stream; 

DESCRIPTION 

getc returns the next character (i.e., byte) from the named 
input stream, as an integer. It also moves the file pointer, if 
defined, ahead one character in stream, getchar is defined as 
getc(stdin) . getc and getchar are macros. 

Fgetc behaves like getc, but is a function rather than a macro. 
Fgetc runs more slowly than getc, but it takes less space per 
invocation and its name can be passed as an argument to a 
function. 

Getw returns the next word (i.e., integer) from the named 
input stream. Getw increments the associated file pointer, if 
defined, to point to the next word. The size of a word is the 
size of an integer and varies from machine to machine. Getw 
assumes no special alignment in the file. 

SEE ALSO 

fclose(3S), ferror(3S), fopen(3S), fread(3S), gets(3S), putc(3S), 
scanf(3S), stdio(3S). 

DIAGNOSTICS 

These functions return the constant EOF at end-of-file or upon 
an error. Because EOF is a valid integer, terror (3S) should be 
used to detect getw errors. 

WARNING 

If the integer value returned by getc, getchar. or fgetc is 
stored into a character variable and then compared against 
the integer constant EOF, the comparison may never succeed, 
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because sign-extension of a character on widening to integer 
is machine-dependent. 

CAVEATS 

Because it is implemented as a macro, getc evaluates a 
stream argument more than once. In particular, getc(*f) does 
not work sensibly. Fgetc should be used instead. 

Because of possible differences in word length and byte ord- 
ering, files written using putw are machine-dependent, and 
may not be read using getw on a different processor. 
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NAME 

getcwd - get path-name of current working directory 

SYNOPSIS 

char *getcwd (buf, size) 
char *buf; 
int size; 

DESCRIPTION 

getcwd returns a pointer to the current directory path name. 
The value of size must be at least two greater than the length 
of the path-name to be returned. 

If buf is a NULL pointer, getcwd will obtain size bytes of space 
using malloc (3C). In this case, the pointer returned by 
getcwd may be used as the argument in a subsequent call to 
free. 

The function is implemented by using popen (3S) to pipe the 
output of the pwd(1) command into the specified string 
space. 

EXAMPLE 

void exitQ, perrorO; 



if ((cwd = getcwd((char *)NULL, 64)) = = NULL) { 
perror("pwd"); 
exit (2); 

} 

printf("%s\n", cwd); 

SEE ALSO 

malloc(3C), popen (3S). 

pwd(1) in the User's Reference Manual. 

DIAGNOSTICS 

Returns NULL with errno set if size is not large enough, or if 
an error occurs in a lower-level function. 
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NAME 

getenv - return value for environment name 

SYNOPSIS 

char *getenv (name) 
char *name; 

DESCRIPTION 

getenv searches the environment list [see environ {5)] for a 
string of the form name = value, and returns a pointer to the 
value in the current environment if such a string is present, 
otherwise a NULL pointer. 

SEE ALSO 

exec(2), putenv(3C), environ(5). 
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NAME 

getgrent, getgrgid, getgrnam, setgrent, endgrent, fgetgrent - 
get group file entry 

SYNOPSIS 

#include <grp.h> 

struct group *getgrent ( ) 

struct group *getgrgid (gid) 
int gid; 

struct group *getgrnam (name) 
char *name; 

void setgrent ( ) 

void endgrent ( ) 

struct group *fgetgrent (f) 
FILE *f; 

DESCRIPTION 

getgrent, getgrgid and getgrnam each return pointers to an 
object with the following structure containing the broken-out 
fields of a line in the /etc/group file. Each line contains a 
"group" structure, defined in the <grp.h> header file. 



struct 

I 

char 
char 
int 
char 

I; 



group 

*gr_name; 
*gr_passwd; 
gr_gid; 
**gr_mem; 



/* the name of the group */ 

/* the encrypted group password */ 

/* the numerical group ID */ 

/* vector of pointers to member names */ 



getgrent when first called returns a pointer to the first group 
structure in the file; thereafter, it returns a pointer to the next 
group structure in the file; so, successive calls may be used to 
search the entire file. Getgrgid searches from the beginning 
of the file until a numerical group id matching gid is found 
and returns a pointer to the particular structure in which it was 
found. Getgrnam searches from the beginning of the file until 
a group name matching name is found and returns a pointer 
to the particular structure in which it was found. If an end-of- 
file or an error is encountered on reading, these functions 
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return a NULL pointer. 

A call to setgrent has the effect of rewinding the group file to 
allow repeated searches. Endgrent may be called to close the 
group file when processing is complete. 

Fgetgrent returns a pointer to the next group structure in the 
stream f , which matches the format of /etc/group. 

FILES 

/etc/group 

SEE ALSO 

getlogin(3C), getpwent(3C), group(4). 

DIAGNOSTICS 

A NULL pointer is returned on EOF or error. 

WARNING 

The above routines use <stdio.h>, which causes them to 
increase the size of programs, not otherwise using standard 
I/O, more than might be expected. 

CAVEAT 

All information is contained in a static area, so it must be 
copied if it is to be saved. 
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NAME 

getlogin - get login name 

SYNOPSIS 

char *getlogin ( ); 

DESCRIPTION 

getlogin returns a pointer to the login name as found in 
/etc/utmp. It may be used in conjunction with getpwnam to 
locate the correct password file entry when the same user ID 
is shared by several login names. 

If getlogin is called within a process that is not attached to a 
terminal, it returns a NULL pointer. 

The correct procedure for determining the login name is to call 
cuserid, or to call getlogin and if it fails to call getpwuid. 

FILES 

/etc/utmp 

SEE ALSO 

cuserid (3S), getgrent(3C), getpwent(3C), utmp(4). 

DIAGNOSTICS 

Returns the NULL pointer if name is not found. 

CAVEAT 

The return values point to static data whose content is 
overwritten by each call. 
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NAME 

getopt - get option letter from argument vector 

SYNOPSIS 

int getopt (argc, argv, optstring) 
int argc; 

char **argv, *opstring; 

extern char *optarg; 
extern int optind, opterr; 

DESCRIPTION 

getopt returns the next option letter in argv that matches a 
letter in optstring. It supports all the rules of the command 
syntax standard (see intro^)). So all new commands will 
adhere to the command syntax standard, they should use 
getoptsfi) or getopt (3C) to parse positional parameters and 
check for options that are legal for that command. 

optstring must contain the option letters the command using 
getopt will recognize; if a letter is followed by a colon, the 
option is expected to have an argument, or group of argu- 
ments, which must be separated from it by white space. 

optarg is set to point to the start of the option-argument on 
return from getopt. 

getopt places in optind the argv index of the next argument 
to be processed, optind is external and is initialized to 1 
before the first call to getopt. 

When all options have been processed (i.e., up to the first 
non-option argument), getopt returns -1. The special option 
"-" may be used to delimit the end of the options; when it is 
encountered, -1 will be returned, and will be skipped. 

DIAGNOSTICS 

getopt prints an error message on standard error and returns 
a question mark (?) when it encounters an option letter not 
included in optstring or no option-argument after an option 
that expects one. This error message may be disabled by set- 
ting opterr to 0. 

EXAMPLE 

The following code fragment shows how one might process 
the arguments for a command that can take the mutually 
exclusive options a and b, and the option o, which requires an 
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option-argument: 

main (argc, argv) 
int argc; 
char **argv; 

{ 

int c; 

extern char *optarg; 
extern int optind; 

while ((c = getopt(argc, argv, "abo:")) != -1) 
switch (c) { 
case 'a': 

if (bflg) 

errflg 4- +; 

else 

aflg+ + ; 

break; 
case 'b 1 : 

if (aflg) 

errflg + + ; 

else 

bproc( ); 

break; 
case 'o': 

ofile = optarg; 

break; 
case '?': 

errflg + +; 

} 

if (errflg) { 

(void)fprintf(stderr, "usage: . . . "); 
exit (2); 

} 

for ( ; optind < argc; optind ++) { 
if (access(argv[optind], 4)) { 

} 
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This code will accept any of the following as equivalent: 

cmd -a -b -o "xxx z yy" file 

cmd -a -b -o "xxx z yy" - file 

cmd -ab -o xxx.z.yy file 

cmd -ab -o "xxx z yy" file 

cmd -o xxx.z.yy -b -a file 

WARNING 

Although the following command syntax rule (see /nfro(1)) 
relaxations are permitted under the current implementation, 
they should not be used because they may not be supported 
in future releases of the system. As in the EXAMPLE section 
above, a and b are options, and the option o requires an 
option-argument: 

cmd -aboxxx file 

(Rule 5 violation: options with 
option-arguments must not be 
grouped with other options) 

cmd -ab -oxxx file 

(Rule 6 violation: there must be 
white space after an option which 
takes an option-argument) 

SEE ALSO 

getopts(1), intro(1) in the User's Reference Manual. 
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NAME 

getpass - read a password 

SYNOPSIS 

char *getpass (prompt) 
char *prompt; 

DESCRIPTION 

getpass reads up to a newline or EOF from the file /dev/tty, 
after prompting on the standard error output with the null- 
terminated string prompt and disabling echoing. A pointer is 
returned to a null-terminated string of at most 8 characters. If 
/dev/tty cannot be opened, a NULL pointer is returned. An 
interrupt will terminate input and send an interrupt signal to 
the calling program before returning. 

FILES 

/dev/tty 

WARNING 

The above routine uses <stdio.h>, which causes it to 
increase the size of programs not otherwise using standard 
I/O, more than might be expected. 

CAVEAT 

The return value points to static data whose content is 
overwritten by each call. 
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NAME 

getpw - get name from UID 

SYNOPSIS 

int getpw (uid, buf) 
int uid; 
char *buf; 

DESCRIPTION 

getpw searches the password file for a user id number that 
equals uid, copies the line of the password file in which uid 
was found into the array pointed to by buf, and returns 0. 
getpw returns non-zero if uid cannot be found. 

This routine is included only for compatibility with prior sys- 
tems and should not be used; see getpwent (3C) for routines 
to use instead. 

FILES 

/etc/ pass wd 

SEE ALSO 

getpwent (3C) , passwd (4) . 

DIAGNOSTICS 

getpw returns non-zero on error. 

WARNING 

The above routine uses <stdio.h>, which causes it to 
increase, more than might be expected, the size of programs 
not otherwise using standard I/O. 
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NAME 

getpwent, getpwuid, getpwnam, setpwent, endpwent, 
fgetpwent - get password file entry 

SYNOPSIS 

#include <pwd.h> 

struct passwd *getpwent ( ) 

struct passwd *getpwuid (uid) 
int uid; 

struct passwd *getpwnam (name) 
char *name; 

void setpwent ( ) 

void endpwent ( ) 

struct passwd *fgetpwent (f) 
FILE *f; 

DESCRIPTION 

getpwent, getpwuid and getpwnam each returns a pointer to 
an object with the following structure containing the broken- 
out fields of a line in the /etc/passwd file. Each line in the file 
contains a "passwd" structure, declared in the <pwd.h> 
header file: 

struct passwd { 



char 


*pw_name; 


char 


*pw_passwd; 


int 


pw_uid; 


int 


pw_gid; 


char 


*pw_age; 


char 


*pw_comment; 


char 


*pw_gecos; 


char 


*pw_dir; 


char 


*pw_shell; 



}; 

This structure is declared in <pwd.h> so it is not necessary 
to redeclare it. 

The fields have meanings described in passwd {4). 

getpwent when first called returns a pointer to the first 
passwd structure in the file; thereafter, it returns a pointer to 
the next passwd structure in the file; so successive calls can 
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be used to search the entire file. Getpwuid searches from the 
beginning of the file until a numerical user id matching uid is 
found and returns a pointer to the particular structure in which 
it was found. Getpwnam searches from the beginning of the 
file until a login name matching name is found, and returns a 
pointer to the particular structure in which it was found. If an 
end-of-file or an error is encountered on reading, these func- 
tions return a NULL pointer. 

A call to setpwent has the effect of rewinding the password 
file to allow repeated searches. Endpwent may be called to 
close the password file when processing is complete. 

Fgetpwent returns a pointer to the next passwd structure in 
the stream f, which matches the format of /etc/ passwd. 

FILES 

/etc/ passwd 

SEE ALSO 

getlogin(3C), getgrent(3C), passwd(4). 

DIAGNOSTICS 

A NULL pointer is returned on EOF or error. 

WARNING 

The above routines use <stdio.h>, which causes them to 
increase the size of programs, not otherwise using standard 
I/O, more than might be expected. 

CAVEAT 

All information is contained in a static area, so it must be 
copied if it is to be saved. 



Page 2 



UP-13712 



GETS(3S) 



NAME 

gets, fgets - get a string from a stream 

SYNOPSIS 

#include <stdio.h> 

char *gets (s) 
char *s; 

char *fgets (s, n, stream) 
char *s; 
int n; 

FILE *stream; 
DESCRIPTION 

gets reads characters from the standard input stream, stdin, 
into the array pointed to by s, until a new-line character is 
read or an end-of-file condition is encountered. The new-line 
character is discarded and the string is terminated with a null 
character. 

Fgets reads characters from the stream into the array pointed 
to by s, until n-1 characters are read, or a new-line character 
is read and transferred to s, or an end-of-file condition is 
encountered. The string is then terminated with a null charac- 
ter. 

SEE ALSO 

f error (3S), fopen(3S), fread(3S), getc(3S), scanf(3S), stdio(3S). 

DIAGNOSTICS 

If end-of-file is encountered and no characters have been 
read, no characters are transferred to s and a NULL pointer is 
returned. If a read error occurs, such as trying to use these 
functions on a file that has not been opened for reading, a 
NULL pointer is returned. Otherwise s is returned. 
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NAME 

getut: getutent, getutid, getutline, pututline, setutent, 
endutent, utmpname - access utmp file entry 

SYNOPSIS 

#include <utmp.h> 

struct utmp *getutent ( ) 

struct utmp *getutid (id) 
struct utmp *id; 

struct utmp *getutline (line) 
struct utmp *line; 

void pututline (utmp) 
struct utmp *utmp; 

void setutent ( ) 

void endutent ( ) 

void utmpname (file) 
char *file; 

DESCRIPTION 

getutent, getutid and getutline each return a pointer to a 
structure of the following type: 



struct 


utmp { 




char 


ut_user[8]; 


/* User login name */ 


char 


ut_id[4]; 


/* /etc/inittab id (usually line #) */ 


char 


ut_line[12]; 


/* device name (console, Inxx) */ 


short 


ut_pid; 


/* process id */ 


short 


ut_type; 


/* type of entry */ 


struct 


exit_status { 




short 


e_termination;/* Process termination status */ 


short 


e_exit; 


/* Process exit status */ 



} ut_exit; /* The exit status of a process 

* marked as DEAD PROCESS. */ 



time_t ut_time; /* time entry was made */ 

}; 

getutent reads in the next entry from a utmp-Wke file. If the 
file is not already open, it opens it. If it reaches the end of the 
file, it fails. 
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getutid searches forward from the current point in the utmp 
file until it finds an entry with a utjype matching id- > utjype 
if the type specified is RUN_LVL, BOOTJIME, OLD TIME or 
NEWJIME. If the type specified in id is INIT_PROCESS, 
LOGIN_PROCESS, USER_PROCESS or DEAD_PROCESS, 
then getutid will return a pointer to the first entry whose type 
is one of these four and whose utjd field matches id->ut_id. 
If the end of file is reached without a match, it fails. 

getutline searches forward from the current point in the utmp 
file until it finds an entry of the type LOGIN_PROCESS or 
USER_PROCESS which also has a utjine string matching the 
line->ut_line string. If the end of file is reached without a 
match, it fails. 

Pututline writes out the supplied utmp structure into the utmp 
file. It uses getutid to search forward for the proper place if it 
finds that it is not already at the proper place. It is expected 
that normally the user of pututline will have searched for the 
proper entry using one of the getut routines. If so, pututline 
will not search. If pututline does not find a matching slot for 
the new entry, it will add a new entry to the end of the file. 

Setutent resets the input stream to the beginning of the file. 
This should be done before each search for a new entry if it is 
desired that the entire file be examined. 

Endutent closes the currently open file. 

Utmpname allows the user to change the name of the file 
examined, from /etc/ utmp to any other file. It is most often 
expected that this other file will be /etc/wtmp. If the file does 
not exist, this will not be apparent until the first attempt to 
reference the file is made. Utmpname does not open the file. 
It just closes the old file if it is currently open and saves the 
new file name. 

FILES 

/etc/utmp 
/etc/wtmp 

SEE ALSO 

ttyslot(3C), utmp(4). 

DIAGNOSTICS 

A NULL pointer is returned upon failure to read, whether for 
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permissions or having reached the end of file, or upon failure 
to write. 

NOTES 

The most current entry is saved in a static structure. Multiple 
accesses require that it be copied before further accesses are 
made. Each call to either getutid or getutline sees the routine 
examine the static structure before performing more I/O. If 
the contents of the static structure match what it is searching 
for, it looks no further. For this reason to use getutline to 
search for multiple occurrences, it would be necessary to zero 
out the static after each success, or getutline would just return 
the same pointer over and over again. There is one exception 
to the rule about removing the structure before further reads 
are done. 

The implicit read done by pututline (if it finds that it is not 
already at the correct place in the file) will not hurt the con- 
tents of the static structure returned by the getutent, getutid 
or getutline routines, if the user has just modified those con- 
tents and passed the pointer back to pututline. 

These routines use buffered standard I/O for input, but the 
pututline uses an unbuffered non-standard write to avoid race 
conditions between processes trying to modify the utmp and 
wtmp files. 
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NAME 

hsearch, hcreate, hdestroy - manage hash search tables 

SYNOPSIS 

#include <search.h> 

ENTRY *hsearch (item, action) 
ENTRY item; 
ACTION action; 

int hcreate (nel) 
unsigned nel; 

void hdestroy ( ) 

DESCRIPTION 

hsearch is a hash-table search routine generalized from Knuth 
(6.4) Algorithm D. It returns a pointer into a hash table indi- 
cating the location at which an entry can be found. Item is a 
structure of type ENTRY (defined in the < search. h > header 
file) containing two pointers: item.key points to the com- 
parison key, and item.data points to any other data to be 
associated with that key. (Pointers to types other than char- 
acter should be cast to pointer-to-character.) Action is a 
member of an enumeration type ACTION indicating the dispo- 
sition of the entry if it cannot be found in the table. ENTER 
indicates that the item should be inserted in the table at an 
appropriate point. FIND indicates that no entry should be 
made. Unsuccessful resolution is indicated by the return of a 
NULL pointer. 

Hcreate allocates sufficient space for the table, and must be 
called before hsearch is used. Nel is an estimate of the max- 
imum number of entries that the table will contain. This 
number may be adjusted upward by the algorithm in order to 
obtain certain mathematically favorable circumstances. 

Hdestroy destroys the search table, and may be followed by 
another call to hcreate. 

NOTES 

hsearch uses open addressing with a multiplicative hash func- 
tion. However, its source code has many other options avail- 
able which the user may select by compiling the hsearch 
source with the following symbols defined to the preproces- 
sor: 
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DIV Use the remainder modulo table size as the 
hash function instead of the multiplicative algo- 
rithm. 

USCR Use a User Supplied Comparison Routine for 
ascertaining table membership. The routine 
should be named hcompar and should behave 
in a mannner similar to strcmp [see 
string (3C)]. 

CHAINED Use a linked list to resolve collisions. If this 
option is selected, the following other options 
become available. 

START Place new entries at the begin- 
ning of the linked list (default is 
at the end). 

SORTUP Keep the linked list sorted by key 
in ascending order. 

SORTDOWN Keep the linked list sorted by key 
in descending order. 

Additionally, there are preprocessor flags for obtaining debug- 
ging printout (-D DEBUG) and for including a test driver in the 
calling routine (-DDRIVER). The source code should be con- 
sulted for further details. 

EXAMPLE 

The following example will read in strings followed by two 
numbers and store them in a hash table, discarding dupli- 
cates. It will then read in strings and find the matching entry 
in the hash table and print it out. 

//include <stdio.h> 
#include <search.h> 

struct info \ /* this is the info stored in the table */ 

int age, room; /* other than the key. */ 

I; 

#define NUM_EMPL 5000 /* ff of elements in search table */ 

main( ) 

\ 

/* space to store strings */ 
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char str i ng_space [ NUM_EMPL*20 ] ; 

/* space to store employee info */ 

struct info info_space[NUM_EMPL]; 

/* next avail space in string_space */ 

char *str_ptr = string_space; 

/* next avail space in info_space */ 

struct info *info_ptr = info_space; 

ENTRY item, *found_item, *hsearch( ); 

/* name to look for in table */ 

char name_to_f ind[30]; 

int i = 0; 

/* create table */ 
(void) hcreate(NUM_EMPL); 

while (scanf ("%s%d%d", str_ptr, &info_ptr->age, 

&info_ptr->room) != EOF && i++ < NUM_EMPL) \ 
/* put info in structure, and structure in item */ 
item. key = str_ptr; 
item. data = (char *)info_ptr; 
str_ptr += strlen(str_ptr ) + 1; 
info_ptr++; 

/* put item into table */ 
(void) hsearch( item, ENTER); 

! 

/* access table */ 

item. key = name_to_f ind; 

while (scanf ("%s", item. key) != EOF) \ 

if ((found_item = hsearch( item, FIND)) != NULL) \ 

/* if item is in the table */ 

(void)printf ("found %s, age = %d, room = %d\n M , 
found_item->key, 

((struct info *)found_item->data)->age, 
((struct info *)f ound_item->data)->room); 

] else [ 

(void)printf ("no such employee %s\n", 
name_to_f ind) 

I 

I 

I 
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SEE ALSO 

bsearch(3C), lsearch(3C), malloc(3C), malloc(3X), string (3C), 
tsearch(3C). 

DIAGNOSTICS 

hsearch returns a NULL pointer if either the action is FIND 
and the item could not be found or the action is ENTER and 
the table is full. 

Hcreate returns zero if it cannot allocate sufficient space for 
the table. 

WARNING 

hsearch and hcreate use malloc (3C) to allocate space. 
CAVEAT 

Only one hash search table may be active at any given time. 
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NAME 

isnan: isnand, isnanf - test for floating point NaN (Not-A- 
Number) 

SYNOPSIS 

#include <ieeefp.h> 

int isnand (dsrc) 
double dsrc; 

int isnanf (fsrc) 
float fsrc; 

DESCRIPTION 

isnand and isnanf return true (1) if the argument dsrc or fsrc 
is a NaN; otherwise they return false (0). 

Neither routine generates any exception, even for signaling 
NaNs. 

isnanf () is implemented as a macro included in <ieeefp.h>. 

SEE ALSO 

fpgetround(3C). 
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NAME 

l3tol, ltol3 - convert between 3-byte integers and long integers 

SYNOPSIS 

void l3tol (Ip, cp, n) 
long *lp; 
char *cp; 
int n; 

void ltol3 (cp, Ip, n) 
char *cp; 
long *lp; 
int n; 

DESCRIPTION 

l3tol converts a list of n three-byte integers packed into a 
character string pointed to by cp into a list of long integers 
pointed to by Ip. 

Ltol3 performs the reverse conversion from long integers {Ip) 
to three-byte integers (cp). 

These functions are useful for file-system maintenance where 
the block numbers are three bytes long. 

SEE ALSO 

fs(4). 

CAVEAT 

Because of possible differences in byte ordering, the numeri- 
cal values of the long integers are machine-dependent. 
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NAME 

lockf - record locking on files 

SYNOPSIS 

#include <unistd.h> 



int lockf (fildes, function, size) 

long size; 

int fildes, function; 

DESCRIPTION 

The lockf command will allow sections of a file to be locked; 
advisory or mandatory write locks depending on the mode 
bits of the file [see chmod{2)]. Locking calls from other 
processes which attempt to lock the locked file section will 
either return an error value or be put to sleep until the 
resource becomes unlocked. All the locks for a process are 
removed when the process terminates. [See fcntl(2) for more 
information about record locking.] 

Fildes is an open file descriptor. The file descriptor must have 
O WRONLY or O RDWR permission in order to establish lock 
with this function call. 

Function is a control value which specifies the action to be 
taken. The permissible values for function are defined in 
<unistd.h> as follows: 



#define F_ULOCK 0 /* Unlock a previously locked section */ 
#define F_LOCK 1 /* Lock a section for exclusive use */ 
#define F_TLOCK 2 /* Test and lock a section for 

exclusive use */ 
#define F_TEST 3 /* Test section for other processes 

locks */ 



All other values of function are reserved for future extensions 
and will result in an error return if not implemented. 

F TEST is used to detect if a lock by another process is 
present on the specified section. F LOCK and F TLOCK both 
lock a section of a file if the section is available. FJJLOCK 
removes locks from a section of the file. 

Size is the number of contiguous bytes to be locked or 
unlocked. The resource to be locked starts at the current 
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offset in the file and extends forward for a positive size and 
backward for a negative size (the preceding bytes up to but 
not including the current offset). If size is zero, the section 
from the current offset through the largest file offset is locked 
(i.e., from the current offset through the present or any future 
end-of-file). An area need not be allocated to the file in order 
to be locked as such locks may exist past the end-of-file. 

The sections locked with F_LOCK or F_TLOCK may, in whole 
or in part, contain or be contained by a previously locked sec- 
tion for the same process. When this occurs, or if adjacent 
sections occur, the sections are combined into a single sec- 
tion. If the request requires that a new element be added to 
the table of active locks and this table is already full, an error 
is returned, and the new section is not locked. 

F_LOCK and F_TLOCK requests differ only by the action 
taken if the resource is not available. F_LOCK will cause the 
calling process to sleep until the resource is available. 
F_TLOCK will cause the function to return a -1 and set errno 
to [EACCES] error if the section is already locked by another 
process. 

F_ULOCK requests may, in whole or in part, release one or 
more locked sections controlled by the process. When sec- 
tions are not fully released, the remaining sections are still 
locked by the process. Releasing the center section of a 
locked section requires an additional eiement in the table of 
active locks. If this table is full, an [EDEADLK] error is 
returned and the requested section is not released. 

A potential for deadlock occurs if a process controlling a 
locked resource is put to sleep by accessing another process's 
locked resource. Thus calls to lockf or fcntl scan for a 
deadlock prior to sleeping on a locked resource. An error 
return is made if sleeping on the locked resource would cause 
a deadlock. 

Sleeping on a resource is interrupted with any signal. The 
alarm {2) command may be used to provide a timeout facility 
in applications which require this facility. 

The lockf utility will fail if one or more of the following are true: 
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[EBADF] 

Fildes is not a valid open descriptor. 
[EACCES] 

Cmd is F_TLOCK or F_TEST and the section is already 
locked by another process. 

[EDEADLK] 

Cmd is F_LOCK and a deadlock would occur. Also the 
cmd is either F_LOCK, F_TLOCK, or F_ULOCK and the 
number of entries in the lock table would exceed the 
number allocated on the system. 

[ECOMM] 

Fildes is on a remote machine and the link to that 
machine is no longer active. 

SEE ALSO 

chmod(2), close(2), creat(2), fcntl(2), intro(2), open(2), read(2), 
write (2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Other- 
wise, a value of -1 is returned and errno is set to indicate the 
error. 

WARNINGS 

Unexpected results may occur in processes that do buffering 
in the user address space. The process may later read/write 
data which is/was locked. The standard I/O package is the 
most common source of unexpected buffering. 

Because in the future the variable errno will be set to EAGAIN 
rather than EACCES when a section of a file is already locked 
by another process, portable application programs should 
expect and test for either value. 
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NAME 

Isearch, Ifind - linear search and update 

SYNOPSIS 

#include <stdio.h> 
#include < search. h> 

char *lsearch ((char *)key, (char *)base, nelp, 
sizeof(*key), compar) 
unsigned *nelp; 
int (*compar)( ); 

char *lfind ((char *)key, (char *)base, nelp, sizeof(*key), 
compar) 
unsigned *nelp; 
int (*compar)( ); 

DESCRIPTION 

Isearch is a linear search routine generalized from Knuth (6.1) 
Algorithm S. It returns a pointer into a table indicating where 
a datum may be found. If the datum does not occur, it is 
added at the end of the table. Key points to the datum to be 
sought in the table. Base points to the first element in the 
table. Nelp points to an integer containing the current 
number of elements in the table. The integer is incremented if 
the datum is added to the table. Compar is the name of the 
comparison function which the user must supply {strcmp, for 
example). It is called with two arguments that point to the ele- 
ments being compared. The function must return zero if the 
elements are equal and non-zero otherwise. 

Lfind is the same as Isearch except that if the datum is not 
found, it is not added to the table. Instead, a NULL pointer is 
returned. 

NOTES 

The pointers to the key and the element at the base of the 
table should be of type pointer-to-element, and cast to type 
pointer-to-character. 

The comparison function need not compare every byte, so 
arbitrary data may be contained in the elements in addition to 
the values being compared. 

Although declared as type pointer-to-character, the value 
returned should be cast into type pointer-to-element. 
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EXAMPLE 

This fragment will read in less than TABSIZE strings of length 
less than ELSIZE and store them in a table, eliminating dupli- 
cates. 

#include <stdio.h> 
#include < search. h> 

#define TABSIZE 50 
#define ELSIZE 120 

char line[ELSIZE], tab [TABSIZE] [ELSIZE], *lsearch( ); 
unsigned nel = 0; 
int strcmp( ); 

while (fgets(line, ELSIZE, stdin) != NULL && 
nel < TABSIZE) 

(void) lsearch(line, (char *)tab, &nel, 
ELSIZE, strcmp); 

SEE ALSO 

bsearch(3C), hsearch(3C), string (3C), tsearch(3C). 

DIAGNOSTICS 

If the searched for datum is found, both /search and Ifind 
return a pointer to it. Otherwise, Ifind returns NULL and 
Isearch returns a pointer to the newly added element. 

BUGS 

Undefined results can occur if there is not enough room in the 
table to add a new item. 
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NAME 

malloc, free, realloc, calloc - main memory allocator 

SYNOPSIS 

char *malloc (size) 
unsigned size; 

void free (ptr) 
char *ptr; 

char *realloc (ptr, size) 
char *ptr; 
unsigned size; 

char *calloc (nelem, elsize) 
unsigned nelem, elsize; 

DESCRIPTION 

malloc and free provide a simple general-purpose memory 
allocation package, malloc returns a pointer to a block of at 
least size bytes suitably aligned for any use. 

The argument to free is a pointer to a block previously allo- 
cated by malloc; after free is performed this space is made 
available for further allocation, but its contents are left undis- 
turbed. 

Undefined results will occur if the space assigned by malloc is 
overrun or if some random number is handed to free. 

malloc allocates the first big enough contiguous reach of free 
space found in a circular search from the last block allocated 
or freed, coalescing adjacent free blocks as it searches. It 
calls sbrk [see brk(2)] to get more memory from the system 
when there is no suitable space already free. 

Realloc changes the size of the block pointed to by ptr to size 
bytes and returns a pointer to the (possibly moved) block. 
The contents will be unchanged up to the lesser of the new 
and old sizes. If no free block of size bytes is available in the 
storage arena, then realloc will ask malloc to enlarge the 
arena by size bytes and will then move the data to the new 
space. 

Realloc also works if ptr points to a block freed since the last 
call of malloc, realloc, or calloc; therefore sequences of free, 
malloc and realloc can exploit the search strategy of malloc 
to do storage compaction. 
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Calloc allocates space for an array of nelem elements of size 
elsize . The space is initialized to zeros. 

Each of the allocation routines returns a pointer to space suit- 
ably aligned (after possible pointer coercion) for storage of 
any type of object. 

SEE ALSO 

brk(2), malloc(3X). 

DIAGNOSTICS 

malloc, realloc and calloc return a NULL pointer if there is no 
available memory or if the arena has been detectably cor- 
rupted by storing outside the bounds of a block. When this 
happens the block pointed to by ptr may be destroyed. 

NOTES 

Search time increases when many objects have been allo- 
cated; that is, if a program allocates but never frees, then 
each successive allocation takes longer. For an alternate, 
more flexible implementation, see malloc (3X). 
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NAME 

memory: memccpy, memchr, memcmp, memcpy, memset - 
memory operations 

SYNOPSIS 

#include < memory. h> 

char *memccpy (s1, s2, c, n) 
char *s1, *s2; 
int c, n; 

char *memchr (s, c, n) 
char *s; 
int c, n; 

int memcmp (s1, s2, n) 
char *s1, *s2; 
int n; 

char *memcpy (s1, s2, n) 
char *s1, *s2; 
int n; 

char *memset (s, c, n) 
char *s; 
int c, n; 

DESCRIPTION 

These functions operate as efficiently as possible on memory 
areas (arrays of characters bounded by a count, not ter- 
minated by a null character). They do not check for the over- 
flow of any receiving memory area. 

Memccpy copies characters from memory area s2 into s1, 
stopping after the first occurrence of character c has been 
copied, or after n characters have been copied, whichever 
comes first. It returns a pointer to the character after the 
copy of c in s1, or a NULL pointer if c was not found in the 
first n characters of s2. 

Memchr returns a pointer to the first occurrence of character 
c in the first n characters of memory area s, or a NULL 
pointer if c does not occur. 

Memcmp compares its arguments, looking at the first n char- 
acters only, and returns an integer less than, equal to, or 
greater than 0, according as s1 is lexicographically less than, 
equal to, or greater than s2. 
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Memcpy copies n characters from memory area s2 to s1. It 
returns s1 . 

Memset sets the first n characters in memory area s to the 
value of character c. It returns s. 

For user convenience, all these functions are declared in the 
optional <memory.h> header file. 

CAVEATS 

Memcmp is implemented by using the most natural character 
comparison on the machine. Thus the sign of the value 
returned when one of the characters has its high order bit set 
is not the same in all implementations and should not be relied 
upon. 

Character movement is performed differently in different 
implementations. Thus overlapping moves may yield 
surprises. 
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NAME 

mktemp - make a unique file name 

SYNOPSIS 

char * mktemp (template) 
char "template; 

DESCRIPTION 

mktemp replaces the entire contents of the string pointed to 
by template by a unique file name, and returns the address of 
template. The string in template should look like a file name 
with six trailing Xs; mktemp will replace the Xs with a letter 
and the current process ID. The letter will be chosen so that 
the resulting name does not duplicate an existing file. 

SEE ALSO 

getpid(2), tmpfile(3S), tmpnam(3S). 

DIAGNOSTIC 

mktemp will assign to template the NULL string if it cannot 
create a unique name. 

CAVEAT 

If called more than 17,576 time in a single process, this func- 
tion will start recycling previously used names. 
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NAME 

monitor - prepare execution profile 

SYNOPSIS 

#include <mon.h> 

void monitor (lowpc, highpc, buffer, bufsize, nfunc) 
int (*lowpc)( ), (*highpc)( ); 
WORD *buffer; 
int bufsize, nfunc; 

DESCRIPTION 

An executable program created by cc -p automatically 
includes calls for monitor with default parameters; monitor 
need not be called explicitly except to gain fine control over 
profiling. 

monitor is an interface to profit {2). Lowpc and highpc are the 
addresses of two functions; buffer is the address of a (user 
supplied) array of bufsize WORDs (defined in the <mon.h> 
header file), monitor arranges to record a histogram of 
periodically sampled values of the program counter, and of 
counts of calls of certain functions, in the buffer. The lowest 
address sampled is that of lowpc and the highest is just below 
highpc. Lowpc may not equal 0 for this use of monitor. At 
most nfunc call counts can be kept; only calls of functions 
compiled with the profiling option -p of cc(1) are recorded. 

For the results to be significant, especially where there are 
small, heavily used routines, it is suggested that the buffer be 
no more than a few times smaller than the range of locations 
sampled. 

To profile the entire program, it is sufficient to use 
extern etext; 

monitor ((int (*)0)2, &etext, buf, bufsize, nfunc); 
Etext lies just above all the program text; see end (3C). 
To stop execution monitoring and write the results, use 

monitor ((int (*)0)O, 0, 0, 0, 0); 

Prof(~\) can then be used to examine the results. 

The name of the file written by monitor is controlled by the 
environment variable PROFDIR. If PROFDIR does not exist, 
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"mon.out" is created in the current directory. If PROFDIR 
exists but has no value, monitor does not do any profiling and 
creates no output file. Otherwise, the value of PROFDIR is 
used as the name of the directory in which to create the out- 
put file. If PROFDIR is dirname, then the file written is 
"dirname/pid . mon.out" where pid is the program's process id. 
(When monitor is called automatically by compiling via cc -p, 
the file created is "dirname /pid. progname" where progname is 
the name of the program.) 

FILES 

mon.out 

SEE ALSO 

cc(1), prof(1), profil(2), end(3C). 

BUGS 

The "dirname/pid. mon.out" form does not work; the 
"dirname /pid. progname" form (automatically called via cc -p) 
does work. 
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NAME 

nlist - get entries from name list 

SYNOPSIS 

#include < nlist. h> 

int nlist (filename, nl) 
char ^filename; 
struct nlist *nl; 

DESCRIPTION 

nlist examines the name list in the executable file whose name 
is pointed to by filename, and selectively extracts a list of 
values and puts them in the array of nlist structures pointed to 
by nl. The name list nl consists of an array of structures con- 
taining names of variables, types and values. The list is ter- 
minated with a null name; that is, a null string is in the name 
position of the structure. Each variable name is looked up in 
the name list of the file. If the name is found, the type and 
value of the name are inserted in the next two fields. The 
type field will be set to 0 unless the file was compiled with the 
-g option. If the name is not found, both entries are set to 0. 
See a.out (4) for a discussion of the symbol table structure. 

This function is useful for examining the system name list kept 
in the file /unix. In this way programs can obtain system 
addresses that are up to date. 

NOTES 

The < nlist. h> header file is automatically included by 
<a.out.h> for compatibility. However, if the only information 
needed from <a.out.h> is for use of nlist, then including 
<a.out.h> is discouraged. If <a.out.h> is included, the line 
"#undef n_name" may need to follow it. 

SEE ALSO 

a. out (4). 

DIAGNOSTICS 

All value entries are set to 0 if the file cannot be read or if it 
does not contain a valid name list. 

nlist returns -1 upon error; otherwise it returns 0. 
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NAME 

perror, errno, sys_errlist, sys_nerr - system error messages 

SYNOPSIS 

void perror (s) 
char *s; 

extern int errno; 
extern char *sys_errlist[ ]; 
extern int sys_nerr; 
DESCRIPTION 

perror produces a message on the standard error output, 
describing the last error encountered during a call to a system 
or library function. The argument string s is printed first, then 
a colon and a blank, then the message and a new-line. (How- 
ever, if s = "" the colon is not printed.) To be of most use, the 
argument string should include the name of the program that 
incurred the error. The error number is taken from the exter- 
nal variable errno, which is set when errors occur but not 
cleared when non-erroneous calls are made. 

To simplify variant formatting of messages, the array of mes- 
sage strings sysjerrlist is provided; errno can be used as an 
index into this table to get the message string without the 
new-line. Sys_nerr is the number of messages in the table; it 
should be checked because new error codes may be added to 
the system before they are added to the table. 

SEE ALSO 

intro(2). 
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NAME 

popen, pclose - initiate pipe to/from a process 

SYNOPSIS 

#include <stdio.h> 

FILE *popen (command, type) 
char *command, *type; 

int pclose (stream) 
FILE *stream; 

DESCRIPTION 

popen creates a pipe between the calling program and the 
command to be executed. The arguments to popen are 
pointers to null-terminated strings. Command consists of a 
shell command line. Type is an I/O mode, either r for reading 
or w for writing. The value returned is a stream pointer such 
that one can write to the standard input of the command, if 
the I/O mode is w, by writing to the file stream; and one can 
read from the standard output of the command, if the I/O 
mode is r, by reading from the file stream. 

A stream opened by popen should be closed by pclose, 
which waits for the associated process to terminate and 
returns the exit status of the command. 

Because open files are shared, a type r command may be 
used as an input filter and a type w as an output filter. 

EXAMPLE 

A typical call may be: 

char *cmd = "Is *.c"; 
FILE *ptr; 

if ((ptr = popen(cmd, "r")) != NULL) 
while (fgets(buf, n, ptr) ! = NULL) 
(void) printf("%s ",buf); 

This will print in stdout [see stdio (3S)] all the file names in the 
current directory that have a ".c" suffix. 

SEE ALSO 

pipe(2), wait(2), fclose(3S), fopen(3S), stdio(3S), system(3S). 

DIAGNOSTICS 

popen returns a NULL pointer if files or processes cannot be 
created. 
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Pclose returns -1 if stream is not associated with a "popened" 
command. 

WARNING 

If the original and "popened" processes concurrently read or 
write a common file, neither should use buffered I/O, because 
the buffering gets all mixed up. Problems with an output filter 
may be forestalled by careful buffer flushing, e.g. with fflush 
[see f close (3S)]. 
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NAME 

printf, fprintf, sprintf - print formatted output 

SYNOPSIS 

#include <stdio.h> 

int printf (format , arg ... ) 
char *format; 

int fprintf (stream, format , arg ... ) 
FILE *stream; 
char *format; 

int sprintf (s, format [ , arg ] . . . ) 
char *s, Mormat; 

DESCRIPTION 

printf places output on the standard output stream stdout. 
Fprintf places output on the named output stream. Sprintf 
places "output," followed by the null character (\0), in con- 
secutive bytes starting at *s; it is the user's responsibility to 
ensure that enough storage is available. Each function returns 
the number of characters transmitted (not including the \0 in 
the case of sprintf), or a negative value if an output error was 
encountered. 

Each of these functions converts, formats, and prints its args 
under control of the format. The format is a character string 
that contains two types of objects: plain characters, which are 
simply copied to the output stream, and conversion specifica- 
tions, each of which results in fetching of zero or more args. 
The results are undefined if there are insufficient args for the 
format. If the format is exhausted while args remain, the 
excess args are simply ignored. 

Each conversion specification is introduced by the character 
%. After the %, the following appear in sequence: 

Zero or more flags, which modify the meaning of the 
conversion specification. 

An optional decimal digit string specifying a minimum 
field width. If the converted value has fewer characters 
than the field width, it will be padded on the left (or right, 
if the left-adjustment flag described below, has been 
given) to the field width. The padding is with blanks 
unless the field width digit string starts with a zero, in 
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which case the padding is with zeros. 

A precision that gives the minimum number of digits to 
appear for the d, i, o, u, x, or X conversions, the number 
of digits to appear after the decimal point for the e, E, 
and f conversions, the maximum number of significant 
digits for the g and G conversion, or the maximum 
number of characters to be printed from a string in s 
conversion. The precision takes the form of a period (.) 
followed by a decimal digit string; a null digit string is 
treated as zero. Padding specified by the precision over- 
rides the padding specified by the field width. 

An optional I (ell) specifying that a following d, i, o, u, x, 
or X conversion character applies to a long integer arg. 
An I before any other conversion character is ignored. 

A character that indicates the type of conversion to be 
applied. 

A field width or precision or both may be indicated by an 
asterisk (*) instead of a digit string. In this case, an integer 
arg supplies the field width or precision. The arg that is actu- 
ally converted is not fetched until the conversion letter is seen, 
so the args specifying field width or precision must appear 
before the arg (if any) to be converted. A negative field width 
argument is taken as a '-' flag followed by a positive field 
width. If the precision argument is negative, it will be changed 
to zero. 

The flag characters and their meanings are: 

The result of the conversion will be left-justified 
within the field. 

+ The result of a signed conversion will always begin 

with a sign (+ or -). 

blank If the first character of a signed conversion is not a 
sign, a blank will be prefixed to the result. This 
implies that if the blank and + flags both appear, 
the blank flag will be ignored. 

# This flag specifies that the value is to be converted 

to an "alternate form." For c, d, i, s, and u conver- 
sions, the flag has no effect. For o conversion, it 
increases the precision to force the first digit of the 
result to be a zero. For x or X conversion, a non- 
zero result will have Ox or OX prefixed to it. For e, 
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E, f, g, and G conversions, the result will always 
contain a decimal point, even if no digits follow the 
point (normally, a decimal point appears in the 
result of these conversions only if a digit follows it). 
For g and G conversions, trailing zeroes will not be 
removed from the result (which they normally are). 

The conversion characters and their meanings are: 

d,i,o,u,x,X The integer arg is converted to signed decimal (d 
or i), unsigned octal, (o), decimal (u), or hexade- 
cimal notation (x or X), respectively; the letters 
abcdef are used for x conversion and the letters 
ABCDEF for X conversion. The precision specifies 
the minimum number of digits to appear; if the 
value being converted can be represented in fewer 
digits, it will be expanded with leading zeroes. The 
default precision is 1. The result of converting a 
zero value with a precision of zero is a null string. 



f The float or double arg is converted to decimal 

notation in the style "[-]ddd.ddd," where the 
number of digits after the decimal point is equal to 
the precision specification. If the precision is miss- 
ing, six digits are output; if the precision is explicitly 
0, no decimal point appears. 

e,E The float or double arg is converted in the style 

"[-]d.ddde±dd," where there is one digit before 
the decimal point and the number of digits after it 
is equal to the precision; when the precision is 
missing, six digits are produced; if the precision is 
zero, no decimal point appears. The E format code 
will produce a number with E instead of e introduc- 
ing the exponent. The exponent always contains at 
least two digits. 

g,G The float or double arg is printed in style f or e (or 
in style E in the case of a G format code), with the 
precision specifying the number of significant 
digits. The style used depends on the value con- 
verted: style e will be used only if the exponent 
resulting from the conversion is less than -4 or 
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greater than the precision. Trailing zeroes are 
removed from the result; a decimal point appears 
only if it is followed by a digit. 

c The character arg is printed. 

s The arg is taken to be a string (character pointer) 

and characters from the string are printed until a 
null character (\0) is encountered or the number of 
characters indicated by the precision specification 
is reached. If the precision is missing, it is taken to 
be infinite, so all characters up to the first null char- 
acter are printed. A NULL value for arg will yield 
undefined results. 

% Print a %; no argument is converted. 

In printing floating point types (float and double), if the 
exponent is 0x7FF and the mantissa is not equal to zero, then 
the output is 

[-]NaNOxdddddddd 

where Oxdddddddd is the hexadecimal representation of the 
leftmost 32 bits of the mantissa. If the mantissa is zero, the 
output is 

[±]inf. 

In no case does a non-existent or small field width cause trun- 
cation of a field; if the result of a conversion is wider than the 
field width, the field is simply expanded to contain the conver- 
sion result. Characters generated by printf and fprintf are 
printed as if putc (3S) had been called. 

EXAMPLES 

To print a date and time in the form "Sunday, July 3, 10:02," 
where weekday and month are pointers to null-terminated 
strings: 

printf ("%s, %s %i, %d:%.2d", weekday, month, day, hour, min); 
To print it to 5 decimal places: 

printf ("pi = %.5f", 4 * atan(1.0)); 
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SEE ALSO 

ecvt(3C), putc(3S), scanf(3S), stdio(3S). 
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NAME 

putc, putchar, fputc, putw - put character or word on a stream 

SYNOPSIS 

#include <stdio.h> 

int putc (c, stream) 
int c; 

FILE *stream; 

int putchar (c) 
int c; 

int fputc (c, stream) 
int c; 

FILE *stream; 

int putw (w, stream) 
int w; 

FILE *stream; 
DESCRIPTION 

putc writes the character c onto the output stream (at the 
position where the file pointer, if defined, is pointing). 
putchar (c) is defined as putc{c, stdout). putc and putchar are 
macros. 

Fputc behaves like putc, but is a function rather than a macro. 
Fputc runs more slowly than putc, but it takes less space per 
invocation and its name can be passed as an argument to a 
function. 

Putw writes the word (i.e. integer) w to the output stream (at 
the position at which the file pointer, if defined, is pointing). 
The size of a word is the size of an integer and varies from 
machine to machine. Putw neither assumes nor causes spe- 
cial alignment in the file. 

SEE ALSO 

fclose(3S), ferror(3S), fopen(3S), fread(3S), printf(3S), 
puts(3S), setbuf(3S), stdio(3S). 

DIAGNOSTICS 

On success, these functions (with the exception of putw) each 
return the value they have written. [Putw returns terror 
(stream)]. On failure, they return the constant EOF. This will 
occur if the file stream is not open for writing or if the output 
file cannot grow. Because EOF is a valid integer, ferror{3S) 
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should be used to detect putw errors. 
CAVEATS 

Because it is implemented as a macro, putc evaluates a 
stream argument more than once. In particular, putc(c, 
*f + +); doesn't work sensibly. Fputc should be used instead. 
Because of possible differences in word length and byte ord- 
ering, files written using putw are machine-dependent, and 
may not be read using getw on a different processor. 
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NAME 

putenv - change or add value to environment 

SYNOPSIS 

int putenv (string) 
char *string; 

DESCRIPTION 

String points to a string of the form "name = value." putenv 
makes the value of the environment variable name equal to 
value by altering an existing variable or creating a new one. 
In either case, the string pointed to by string becomes part of 
the environment, so altering the string will change the environ- 
ment. The space used by string is no longer used once a new 
string-defining name is passed to putenv. 

SEE ALSO 

exec(2), getenv(3C), malloc(3C), environ(5). 

DIAGNOSTICS 

putenv returns non-zero if it was unable to obtain enough 
space via malloc for an expanded environment, otherwise 
zero. 

WARNINGS 

putenv manipulates the environment pointed to by environ, 
and can be used in conjunction with getenv. However, envp 
(the third argument to main) is not changed. 
This routine uses malloc (3C) to enlarge the environment. 
After putenv is called, environmental variables are not in alpha- 
betical order. 

A potential error is to call putenv with an automatic variable as 
the argument, then exit the calling function while string is still 
part of the environment. 
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NAME 

putpwent - write password file entry 

SYNOPSIS 

#include <pwd.h> 

int putpwent (p, f) 
struct passwd *p; 
FILE *f; 

DESCRIPTION 

putpwent is the inverse of getpwent (3C) . Given a pointer to a 
passwd structure created by getpwent (or getpwuid or 
getpwnam), putpwent writes a line on the stream /, which 
matches the format of /etc/pa sswd. 

SEE ALSO 

getpwent (3C). 

DIAGNOSTICS 

putpwent returns non-zero if an error was detected during its 
operation, otherwise zero. 

WARNING 

The above routine uses <stdio.h>, which causes it to 
increase the size of programs, not otherwise using standard 
I/O, more than might be expected. 
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NAME 

puts, fputs - put a string on a stream 

SYNOPSIS 

#include <stdio.h> 

int puts (s) 
char *s; 

int fputs (s, stream) 
char *s; 
FILE *stream; 

DESCRIPTION 

puts writes the null-terminated string pointed to by s .followed 
by a new-line character, to the standard output stream stdout. 

Fputs writes the null-terminated string pointed to by s to the 
named output stream. 

Neither function writes the terminating null character. 
SEE ALSO 

ferror(3S), fopen(3S), fread(3S), printf(3S), putc(3S), stdio(3S). 

DIAGNOSTICS 

Both routines return EOF on error. This will happen if the rou- 
tines try to write on a file that has not been opened for writ- 
ing. 

NOTES 

purs appends a new-line character while fputs does not. 



UP-13712 



Page 1 



PUTS(3S) 



[This page left blank.] 



Page 2 



UP-13712 



QSORT(3C) 



NAME 

qsort - quicker sort 

SYNOPSIS 

void qsort ((char *) base, nel, sizeof (*base), compar) 
unsigned nel; 
int (*compar)( ); 

DESCRIPTION 

qsort is an implementation of the quicker-sort algorithm. It 
sorts a table of data in place. 

Base points to the element at the base of the table. Nel is 
the number of elements in the table. Compar is the name of 
the comparison function, which is called with two arguments 
that point to the elements being compared. As the function 
must return an integer less than, equal to, or greater than 
zero, so must the first argument to be considered be less 
than, equal to, or greater than the second. 

NOTES 

The pointer to the base of the table should be of type 
pointer-to-element, and cast to type pointer-to-character. 
The comparison function need not compare every byte, so 
arbitrary data may be contained in the elements in addition to 
the values being compared. 

The order in the output of two items which compare as equal 
is unpredictable. 

SEE ALSO 

bsearch(3C), lsearch(3C), string (3C). 
sort(1) in the User's Reference Manual'. 



UP-13712 



Page 1 



QSORT(3C) 



[This page left blank.] 



Page 2 



UP-13712 



RAND(3C) 



NAME 

rand, srand - simple random-number generator 

SYNOPSIS 
int rand ( ) 

void srand (seed) 
unsigned seed; 

DESCRIPTION 

rand uses a multiplicative congruential random-number gen- 
erator with period 2 that returns successive pseudo-random 
numbers in the range from 0 to 2 15 -1. 

Srand can be called at any time to reset the random-number 
generator to a random starting point. The generator is initially 
seeded with a value of 1 . 

NOTES 

The spectral properties of rand are limited. Drand48 (3C) pro- 
vides a much better, though more elaborate, random-number 
generator. 

SEE ALSO 

drand48(3C). 
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NAME 

scant, fscanf, sscanf - convert formatted input 

SYNOPSIS 

#include <stdio.h> 

int scanf (format [ , pointer ] ... ) 
char *format; 

int fscanf (stream, format [ , pointer ] . . . ) 
FILE *stream; 
char *format; 

int sscanf (s, format [ , pointer ] ... ) 
char *s, *format; 

DESCRIPTION 

scanf reads from the standard input stream stdin. Fscanf 
reads from the named input stream. Sscanf reads from the 
character string s. Each function reads characters, interprets 
them according to a format, and stores the results in its argu- 
ments. Each expects, as arguments, a control string format 
described below, and a set of pointer arguments indicating 
where the converted input should be stored. The results are 
undefined in there are insufficient args for the format. If the 
format is exhausted while args remain, the excess args are 
simply ignored. 

The control string usually contains conversion specifications, 
which are used to direct interpretation of input sequences. 
The control string may contain: 

1. White-space characters (blanks, tabs, new-lines, or form- 
feeds) which, except in two cases described below, cause 
input to be read up to the next non-white-space character. 

2. An ordinary character (not %), which must match the next 
character of the input stream. 

3. Conversion specifications, consisting of the character %, an 
optional assignment suppressing character *, an optional 
numerical maximum field width, an optional I (ell) or h indi- 
cating the size of the receiving variable, and a conversion 
code. 

A conversion specification directs the conversion of the next 
input field; the result is placed in the variable pointed to by 
the corresponding argument, unless assignment suppression 
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was indicated by *. The suppression of assignment provides 
a way of describing an input field which is to be skipped. An 
input field is defined as a string of non-space characters; it 
extends to the next inappropriate character or until the field 
width, if specified, is exhausted. For all descriptors except "[" 
and "c", white space leading an input field is ignored. 

The conversion code indicates the interpretation of the input 
field; the corresponding pointer argument must usually be of 
a restricted type. For a suppressed field, no pointer argument 
is given. The following conversion codes are legal: 

% a single % is expected in the input at this point; no 
assignment is done. 

d a decimal integer is expected; the corresponding argu- 
ment should be an integer pointer. 

u an unsigned decimal integer is expected; the correspond- 
ing argument should be an unsigned integer pointer. 

0 an octal integer is expected; the corresponding argument 
should be an integer pointer. 

x a hexadecimal integer is expected; the corresponding 
argument should be an integer pointer. 

1 an integer is expected; the corresponding argument 
should be an integer pointer. It will store the value of the 
next input item interpreted according to C conventions: a 
leading "0" implies octal; a leading "Ox" implies hexade- 
cimal; otherwise, decimal. 

n stores in an integer argument the total number of charac- 
ters (including white space) that have been scanned so 
far since the function call. No input is consumed. 

e.f.g 

a floating point number is expected; the next field is con- 
verted accordingly and stored through the corresponding 
argument, which should be a pointer to a float. The input 
format for floating point numbers is an optionally signed 
string of digits, possibly containing a decimal point, 
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followed by an optional exponent field consisting of an E 
or an e, followed by an optional , -, or space, followed by 
an integer. 

s a character string is expected; the corresponding argu- 
ment should be a character pointer pointing to an array of 
characters large enough to accept the string and a ter- 
minating \0, which will be added automatically. The input 
field is terminated by a white-space character. 

c a character is expected; the corresponding argument 
should be a character pointer. The normal skip over white 
space is suppressed in this case; to read the next non- 
space character, use %1s. If a field width is given, the 
corresponding argument should refer to a character 
array; the indicated number of characters is read. 

[ indicates string data and the normal skip over leading 
white space is suppressed. The left bracket is followed by 
a set of characters, which we will call the scanset, and a 
right bracket; the input field is the maximal sequence of 
input characters consisting entirely of characters in the 
scanset. The circumflex (~), when it appears as the first 
character in the scanset, serves as a complement opera- 
tor and redefines the scanset as the set of all characters 
not contained in the remainder of the scanset string. 
There are some conventions used in the construction of 
the scanset. A range of characters may be represented 
by the construct first-last, thus [0123456789] may be 
expressed [0-9]. Using this convention, first must be lexi- 
cally less than or equal to last, or else the dash will stand 
for itself. The dash will also stand for itself whenever it is 
the first or the last character in the scanset. To include 
the right square bracket as an element of the scanset, it 
must appear as the first character (possibly preceded by 
a circumflex) of the scanset, and in this case it will not be 
syntactically interpreted as the closing bracket. The 
corresponding argument must point to a character array 
large enough to hold the data field and the terminating \0, 
which will be added automatically. At least one character 
must match for this conversion to be considered success- 
ful. 
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The conversion characters d, u, o, x and i may be preceded 
by I or h to indicate that a pointer to long or to short rather 
than to int is in the argument list. Similarly, the conversion 
characters e, f, and g may be preceded by I to indicate that a 
pointer to double rather than to float is in the argument list. 
The I or h modifier is ignored for other conversion characters. 

scant conversion terminates at EOF, at the end of the control 
string, or when an input character conflicts with the control 
string. In the latter case, the offending character is left 
unread in the input stream. 

scant returns the number of successfully matched and 
assigned input items; this number can be zero in the event of 
an early conflict between an input character and the control 
string. If the input ends before the first conflict or conversion, 
EOF is returned. 

EXAMPLES 

The call: 

int n ; float x; char name[50]; 

n = scanf ("%d%f%s", &i, &x, name); 

with the input line: 

25 54.32E-1 thompson 

will assign to n the value 3, to / the value 25, to x the value 
5.432, and name will contain thompsorAO . Or: 

int i, j; float x; char name[50]; 

(void) scanf ("%i%2d%f%*d %[0-9] ", &j, &i, &x, name); 

with input: 

011 56789 0123 56a72 

will assign 9 to /, 56 to /, 789.0 to x, skip 0123, and place the 
string 56\0 in name. The next call to getchar [see getc (3S)] 
will return a. Or: 

int i, j, s, e; char name[50]; 

(void) scanf ("%i %i %n%s%n", &i, &j, &s, name, &e); 
with input: 

0x1 1 Oxy johnson 
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will assign 17 to /', 0 to j, 6 to s, will place the string xy\0 in 
name, and will assign 8 to e. Thus, the length of name is e - s 
= 2 . The next call to getchar [see getc (3S)] will return a 
blank. 

SEE ALSO 

getc(3S), printf(3S), stdio(3S), strtod(3C), strtol(3C). 

DIAGNOSTICS 

These functions return EOF on end of input and a short count 
for missing or illegal data items. 

CAVEATS 

Trailing white space (including a new-line) is left unread unless 
matched in the control string. 
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NAME 

setbuf, setvbuf - assign buffering to a stream 

SYNOPSIS 

#include <stdio.h> 

void setbuf (stream, buf) 
FILE *stream; 
char *buf; 

int setvbuf (stream, buf, type, size) 
FILE *stream; 
char *buf; 
int type, size; 

DESCRIPTION 

setbuf may be used after a stream has been opened but 
before it is read or written. It causes the array pointed to by 
buf to be used instead of an automatically allocated buffer. If 
buf is the NULL pointer input/output will be completely unbuf- 
fered. 

A constant BUFSIZ, defined in the <stdio.h> header file, 
tells how big an array is needed: 

char buf[BUFSIZ]; 

Setvbuf may be used after a stream has been opened but 
before it is read or written. Type determines how stream will 
be buffered. Legal values for type (defined in stdio.h) are: 

JOFBF causes input/output to be fully buffered. 

IOLBF causes output to be line buffered; the buffer will 
be flushed when a newline is written, the buffer 
is full, or input is requested. 

JONBF causes input/output to be completely unbuf- 
fered. 

If buf is not the NULL pointer, the array it points to will be 
used for buffering, instead of an automatically allocated 
buffer. Size specifies the size of the buffer to be used. The 
constant BUFSIZ in < stdio.h > is suggested as a good buffer 
size. If input/output is unbuffered, buf and size are ignored. 

By default, output to a terminal is line buffered and all other 
input/output is fully buffered. 
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SEE ALSO 

fopen(3S), getc(3S), malloc(3C), putc(3S), stdio(3S). 
DIAGNOSTICS 

If an illegal value for type or size is provided, setvbuf returns a 
non-zero value. Otherwise, the value returned will be zero. 

NOTES 

A common source of error is allocating buffer space as an 
"automatic" variable in a code block, and then failing to close 
the stream in the same block. 
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NAME 

setjmp, longjmp - non-local goto 

SYNOPSIS 

#include < setjmp. h> 

int setjmp (env) 
jmp buf env; 

void longjmp (env, val) 
jmp_buf env; 
int val; 

DESCRIPTION 

These functions are useful for dealing with errors and inter- 
rupts encountered in a low-level subroutine of a program. 

setjmp saves its stack environment in env (whose type, 
jmp_buf, is defined in the <setjmp.h> header file) for later 
use by longjmp. It returns the value 0. 

Longjmp restores the environment saved by the last call of 
setjmp with the corresponding env argument. After longjmp is 
completed, program execution continues as if the correspond- 
ing call of setjmp (which must not itself have returned in the 
interim) had just returned the value val. Longjmp cannot 
cause setjmp to return the value 0. If longjmp is invoked with 
a second argument of 0, setjmp will return 1. At the time of 
the second return from setjmp, all accessible data have values 
as of the time longjmp is called. However, global variables will 
have the expected values, i.e. those as of the time of the 
longjmp (see example). 

EXAMPLE 

^include <setjmp.h> 

jmp_buf env; 
int i = 0; 
main () 
\ 

void exit( ); 

if (setjmp (env) != 0) \ 

(void) printf ("value of i on 2nd return from setjmp: 
%d\n", i); 

exit(0); 
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I 

(void) printf ("value of i on 1st return from setjmp: 
%d\n\ i ); 

i = i; 
g(); 

/*NOTREACHED*/ 



g() 

\ 

longjmp (env, 1); 
/*NOTREACHED*/ 

I 

If the a.out resulting from this C language code is run, the 
output will be: 

value of i on 1st return from setjmp: 0 

value of i on 2nd return from setjmp: 1 

SEE ALSO 

signal (2). 

WARNING 

If longjmp is called even though env was never primed by a 
call to setjmp, or when the last such call was in a function 
which has since returned, absolute chaos is guaranteed. 

BUGS 

The values of the registers on the second return from setjmp 
are the register values at the time of the first call to setjmp, 
not those at the time of the longjmp. This means that vari- 
ables in a given function may behave differently in the pres- 
ence of setjmp, depending on whether they are register or 
stack variables. 
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NAME 

sleep - suspend execution for interval 

SYNOPSIS 

unsigned sleep (seconds) 
unsigned seconds; 

DESCRIPTION 

The current process is suspended from execution for the 
number of seconds specified by the argument. The actual 
suspension time may be less than that requested for two rea- 
sons: (1) Because scheduled wakeups occur at fixed 1 -second 
intervals, (on the second, according to an internal clock) and 
(2) because any caught signal will terminate the sleep follow- 
ing execution of that signal's catching routine. Also, the 
suspension time may be longer than requested by an arbitrary 
amount due to the scheduling of other activity in the system. 
The value returned by sleep will be the "unslept" amount (the 
requested time minus the time actually slept) in case the caller 
had an alarm set to go off earlier than the end of the 
requested sleep time, or premature arousal due to another 
caught signal. 

The routine is implemented by setting an alarm signal and 
pausing until it (or some other signal) occurs. The previous 
state of the alarm signal is saved and restored. The calling 
program may have set up an alarm signal before calling 
sleep. If the sleep time exceeds the time till such alarm sig- 
nal, the process sleeps only until the alarm signal would have 
occurred. The caller's alarm catch routine is executed just 
before the sleep routine returns. But if the sleep time is less 
than the time till such alarm, the prior alarm time is reset to go 
off at the same time it would have without the intervening 
sleep . 

SEE ALSO 

alarm (2), pause (2), signal (2). 
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NAME 

ssignal, gsignal - software signals 

SYNOPSIS 

#include < signal. h> 

int (*ssignal (sig, action))( ) 
int sig, (*action)( ); 

int gsignal (sig) 
int sig; 

DESCRIPTION 

ssignal and gsignal implement a software facility similar to 
signal (2). This facility is used by the Standard C Library to 
enable users to indicate the disposition of error conditions, 
and is also made available to users for their own purposes. 

Software signals made available to users are associated with 
integers in the inclusive range 1 through 16. A call to ssignal 
associates a procedure, action, with the software signal sig; 
the software signal, sig, is raised by a call to gsignal. Raising 
a software signal causes the action established for that signal 
to be taken . 

The first argument to ssignal is a number identifying the type 
of signal for which an action is to be established. The second 
argument defines the action; it is either the name of a (user- 
defined) action function or one of the manifest constants 
SIG_DFL (default) or SIG_IGN (ignore), ssignal returns the 
action previously established for that signal type; if no action 
has been established or the signal number is illegal, ssignal 
returns SIG DFL. 

Gsignal raises the signal identified by its argument, sig: 

If an action function has been established for sig, then 
that action is reset to SIG_DFL and the action function is 
entered with argument sig. Gsignal returns the value 
returned to it by the action function. 

If the action for sig is SIG_IGN, gsignal returns the value 
1 and takes no other action. 

If the action for sig is SIG_DFL, gsignal returns the 
value 0 and takes no other action. 
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If sig has an illegal value or no action was ever specified 
for sig, gsignal returns the value 0 and takes no other 
action. 

SEE ALSO 

signal (2), sigset(2). 

NOTES 

There are some additional signals with numbers outside the 
range 1 through 16 which are used by the Standard C Library 
to indicate error conditions. Thus, some signal numbers out- 
side the range 1 through 16 are legal, although their use may 
interfere with the operation of the Standard C Library. 
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NAME 

stdio - standard buffered input/output package 

SYNOPSIS 

#include < stdio. h> 

FILE *stdin, *stdout, *stderr; 

DESCRIPTION 

The functions described in the entries of sub-class 3S of this 
manual constitute an efficient, user-level I/O buffering scheme. 
The in-line macros getc (3S) and putc (3S) handle characters 
quickly. The macros getchar and putchar, and the higher-level 
routines fgetc, fgets, fprintf, fputc, fputs, tread, f scant , fwrite, 
gets, getw, printf, puts, putw, and scant all use or act as if 
they use getc and putc; they can be freely intermixed. 

A file with associated buffering is called a stream and is 
declared to be a pointer to a defined type FILE. Fopen (3S) 
creates certain descriptive data for a stream and returns a 
pointer to designate the stream in all further transactions. 
Normally, there are three open streams with constant pointers 
declared in the < stdio. h> header file and associated with the 
standard open files: 

stdin standard input file 
stdout standard output file 
stderr standard error file 

A constant NULL (0) designates a nonexistent pointer. 

An integer-constant EOF (-1) is returned upon end-of-file or 
error by most integer functions that deal with streams (see the 
individual descriptions for details). 

An integer constant BUFSIZ specifies the size of the buffers 
used by the particular implementation. 

Any program that uses this package must include the header 
file of pertinent macro definitions, as follows: 

#include <stdio.h> 

The functions and constants mentioned in the entries of sub- 
class 3S of this manual are declared in that header file and 
need no further declaration. The constants and the following 
"functions" are implemented as macros (redeclaration of 
these names is perilous): getc, getchar, putc, putchar, terror, 
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feof, clearer r, and fileno. 

Output streams, with the exception of the standard error 
stream stderr, are by default buffered if the output refers to a 
file and line-buffered if the output refers to a terminal. The 
standard error output stream stderr is by default unbuffered, 
but use of freopen [see fopen (3S)] will cause it to become 
buffered or line-buffered. When an output stream is unbuf- 
fered, information is queued for writing on the destination file 
or terminal as soon as written; when it is buffered, many char- 
acters are saved up and written as a block. When it is 
line-buffered, each line of output is queued for writing on the 
destination terminal as soon as the line is completed (that is, 
as soon as a new-line character is written or terminal input is 
requested). Setbuf (3S) or set vbufty in setbuf {3S) may be used 
to change the stream's buffering strategy. 

SEE ALSO 

open(2), close(2), lseek(2), pipe(2), read(2), write(2), 
ctermid(3S), cuserid(3S), fclose(3S), ferror(3S), fopen (3S), 
fread(3S), fseek(3S), getc(3S), gets(3S), popen(3S), printf(3S), 
putc(3S), puts(3S), scanf(3S), setbuf (3S), system (3S), 
tmpfile(3S), tmpnam(3S), ungetc(3S). 

DIAGNOSTICS 

Invalid stream pointers will usually cause grave disorder, possi- 
bly including program termination. Individual function descrip- 
tions describe the possible error conditions. 
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NAME 

stdipc: ftok - standard interprocess communication package 

SYNOPSIS 

#include < sys/types.h > 
#include <sys/ipc.h> 

key_t ftok(path, id) 
char *path; 
char id; 

DESCRIPTION 

All interprocess communication facilities require the user to 
supply a key to be used by the msgget{2), semget(2), and 
shmget{2) system calls to obtain interprocess communication 
identifiers. One suggested method for forming a key is to use 
the ftok subroutine described below. Another way to compose 
keys is to include the project ID in the most significant byte 
and to use the remaining portion as a sequence number. 
There are many other ways to form keys, but it is necessary 
for each system to define standards for forming them. If 
some standard is not adhered to, it will be possible for unre- 
lated processes to unintentionally interfere with each other's 
operation. Therefore, it is strongly suggested that the most 
significant byte of a key in some sense refer to a project so 
that keys do not conflict across a given system. 

Ftok returns a key based on path and id that is usable in sub- 
sequent msgget, semget, and shmget system calls. Path 
must be the path name of an existing file that is accessible to 
the process. Id is a character which uniquely identifies a pro- 
ject. Note that ftok will return the same key for linked files 
when called with the same id and that it will return different 
keys when called with the same file name but different ids. 

SEE ALSO 

intro(2), msgget(2), semget(2), shmget(2). 

DIAGNOSTICS 

Ftok returns (key_t) -1 if path does not exist or if it is not 
accessible to the process. 

WARNING 

If the file whose path is passed to ftok is removed when keys 
still refer to the file, future calls to ftok with the same path and 
id will return an error. If the same file is recreated, then ftok is 
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likely to return a different key than it did the original time it 
was called. 
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NAME 

string: strcat, strdup, strncat, strcmp, strncmp, strcpy, 
strncpy, strlen, strchr, strrchr, strpbrk, strspn, strcspn, strtok - 
string operations 

SYNOPSIS 

#include < string. h> 
#include < sys/types.h > 

char *strcat (s1, s2) 
char *s1, *s2; 

char *strdup (s1) 
char *s1; 

char * strncat (s1, s2, n) 
char *s1, *s2; 
sizet n; 

int strcmp (s1, s2) 
char *s1, *s2; 

int strncmp (s1, s2, n) 
char *s1, *s2; 
size_t n; 

char *strcpy (s1, s2) 
char *s1, *s2; 

char *strncpy (s1, s2, n) 
char *s1, *s2; 
size t n; 

int strlen (s) 
char *s; 

char *strchr (s, c) 
char *s; 
int c; 

char *strrchr (s, c) 
char *s; 
int c; 

char *strpbrk (s1, s2) 
char *s1, *s2; 

int strspn (s1, s2) 
char *s1, *s2; 
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int strcspn (s1, s2) 
char *s1, *s2; 

char *strtok (s1, s2) 
char *s1, *s2; 

DESCRIPTION 

The arguments s1 , s2 and s point to strings (arrays of charac- 
ters terminated by a null character). The functions strcat, 
strncat, strcpy, and strncpy all alter s1. These functions do 
not check for overflow of the array pointed to by s1 . 

Strcat appends a copy of string s2 to the end of string s1 . 

Strdup returns a pointer to a new string which is a duplicate of 
the string pointed to by s1. The space for the new string is 
obtained using malloc (3C). If the new string can not be 
created, null is returned. 

Strncat appends at most n characters. Each returns a pointer 
to the null-terminated result. 

Strcmp compares its arguments and returns an integer less 
than, equal to, or greater than 0, according as s1 is lexico- 
graphically less than, equal to, or greater than s2. Strncmp 
makes the same comparison but looks at at most n charac- 
ters. 

Strcpy copies string s2 to s1 , stopping after the null character 
has been copied. Strncpy copies exactly n characters, trun- 
cating s2 or adding null characters to s1 if necessary. The 
result will not be null-terminated if the length of s2 is n or 
more. Each function returns s1 . 

Strlen returns the number of characters in s, not including the 
terminating null character. 

Strchr {strrchr) returns a pointer to the first (last) occurrence 
of character c in string s, or a NULL pointer if c does not 
occur in the string. The null character terminating a string is 
considered to be part of the string. 

Strpbrk returns a pointer to the first occurrence in string s1 of 
any character from string s2, or a NULL pointer if no charac- 
ter from s2 exists in s1 . 

Strspn {strcspn) returns the length of the initial segment of 
string s1 which consists entirely of characters from (not from) 
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string s2. 

Strtok considers the string s1 to consist of a sequence of zero 
or more text tokens separated by spans of one or more char- 
acters from the separator string s2. The first call (with pointer 
s1 specified) returns a pointer to the first character of the first 
token, and will have written a null character into s1 immedi- 
ately following the returned token. The function keeps track of 
its position in the string between separate calls, so that subse- 
quent calls (which must be made with the first argument a 
NULL pointer) will work through the string s1 immediately fol- 
lowing that token. In this way subsequent calls will work 
through the string s1 until no tokens remain. The separator 
string s2 may be different from call to call. When no token 
remains in s1, a NULL pointer is returned. 

For user convenience, all these functions are declared in the 
optional <string.h> header file. 

SEE ALSO 

malloc(3C), malloc(3X). 

CAVEATS 

Strcmp and strncmp are implemented by using the most 
natural character comparison on the machine. Thus the sign 
of the value returned when one of the characters has its high- 
order bit set not the same in all implementations and should 
not be relied upon. 

Character movement is performed differently in different 
implementations. Thus overlapping moves may yield 
surprises. 
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NAME 

strtod, atof - convert string to double-precision number 

SYNOPSIS 

double strtod (str, ptr) 
char *str, **ptr; 

double atof (str) 
char *str; 

DESCRIPTION 

strtod returns as a double-precision floating-point number the 
value represented by the character string pointed to by str. 
The string is scanned up to the first unrecognized character. 

strtod recognizes an optional string of "white-space" charac- 
ters [as defined by isspace in ctype (3C)], then an optional 
sign, then a string of digits optionally containing a decimal 
point, then an optional e or E followed by an optional sign or 
space, followed by an integer. 

If the value of ptr is not (char **)NULL, a pointer to the char- 
acter terminating the scan is returned in the location pointed 
to by ptr. If no number can be formed, *ptr is set to str, and 
zero is returned. 

Atof (str) is equivalent to strtod(str, (char **)NULL). 

SEE ALSO 

ctype(3C), scanf(3S), strtol(3C). 

DIAGNOSTICS 

If the correct value would cause overflow, ± HUGE (as defined 
in <math.h>) is returned (according to the sign of the value), 
and errno is set to ERANGE. 

If the correct value would cause underflow, zero is returned 
and errno is set to ERANGE. 



UP-13712 



Page 1 



STRTOD(3C) 



[This page left blank.] 



Page 2 



UP-13712 



STRTOL(3C) 



NAME 

strtol, atol, atoi - convert string to integer 

SYNOPSIS 

long strtol (str, ptr, base) 
char *str, **ptr; 
int base; 

long atol (str) 
char *str; 

int atoi (str) 
char *str; 

DESCRIPTION 

strtol returns as a long integer the value represented by the 
character string pointed to by str. The string is scanned up to 
the first character inconsistent with the base. Leading "white- 
space" characters [as defined by isspace in ctype (3C)] are 
ignored. 

If the value of ptr is not (char **)NULL, a pointer to the char- 
acter terminating the scan is returned in the location pointed 
to by ptr. If no integer can be formed, that location is set to 
str, and zero is returned. 

If base is positive (and not greater than 36), it is used as the 
base for conversion. After an optional leading sign, leading 
zeros are ignored, and "Ox" or "OX" is ignored if base is 16. 

Lf base is zero, the string itself determines the base thusly: 
After an optional leading sign a leading zero indicates octal 
conversion, and a teading "Ox" or "OX" hexadecimal conver- 
sion. Otherwise, decimal conversion is used 

Truncation from long to int can, of course, take place upon 
assignment or by an explicit cast. 

Atol(str) is equivalent to strtol(str, (char **)NULL, 10) . 

Atoi(str) is equivalent to (int) strtol(str, (char **)NULL, 10) . 

SEE ALSO 

ctype(3C), scanf(3S), strtod(3C). 

CAVEAT 

Overflow conditions are ignored. 
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NAME 

swab - swap bytes 

SYNOPSIS 

void swab (from, to, nbytes) 
char *from, *to; 
int nbytes; 

DESCRIPTION 

swab copies nbytes bytes pointed to by from to the array 
pointed to by to, exchanging adjacent even and odd bytes. 
Nbytes should be even and non-negative. If nbytes is odd and 
positive swab uses noyfes-1 instead. If nbytes is negative, 
swab does nothing. 
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NAME 

system - issue a shell command 

SYNOPSIS 

#include <stdio.h> 

int system (string) 
char * string; 

DESCRIPTION 

system causes the string to be given to s/?(1) as input, as if 
the string had been typed as a command at a terminal. The 
current process waits until the shell has completed, then 
returns the exit status of the shell. 

FILES 

/bin/sh 

SEE ALSO 

exec (2). 

sh(1) in the User's Reference Manual. 
DIAGNOSTICS 

system forks to create a child process that in turn exec's 
/bin/sh in order to execute string. If the fork or exec fails, 
system returns a negative value and sets errno. 
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NAME 

tmpfile - create a temporary file 

SYNOPSIS 

#include <stdio.h> 

FILE *tmpfile () 

DESCRIPTION 

tmpfile creates a temporary file using a name generated by 
tmpnam (3S), and returns a corresponding FILE pointer. If the 
file cannot be opened, an error message is printed using 
perror (3C), and a NULL pointer is returned. The file will 
automatically be deleted when the process using it terminates. 
The file is opened for update ("w + "). 

SEE ALSO 

creat(2), unlink(2), fopen(3S), mktemp(3C), perror(3C), 
stdio(3S), tmpnam(3S). 
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NAME 

tmpnam, tempnam - create a name for a temporary file 

SYNOPSIS 

#include <stdio.h> 

char *tmpnam (s) 
char *s; 

char *tempnam (dir, pfx) 
char *dir, *pfx; 

DESCRIPTION 

These functions generate file names that can safely be used 
for a temporary file. 

tmpnam always generates a file name using the path-prefix 
defined as P_tmpdir in the <stdio.h> header file. If s is 
NULL, tmpnam leaves its result in an internal static area and 
returns a pointer to that area. The next call to tmpnam will 
destroy the contents of the area. If s is not NULL, it is 
assumed to be the address of an array of at least L_tmpnam 
bytes, where L_tmpnam is a constant defined in <stdio.h>\ 
tmpnam places its result in that array and returns s. 

Tempnam allows the user to control the choice of a directory. 
The argument dir points to the name of the directory in which 
the file is to be created. If dir is NULL or points to a string 
that is not a name for an appropriate directory, the path-prefix 
defined as P_tmpdir in the <stdio.h> header file is used. If 
that directory is not accessible, /tmp will be used as a last 
resort. This entire sequence can be up-staged by providing 
an environment variable TMPDIR in the user's environment, 
whose value is the name of the desired temporary-file direc- 
tory. 

Many applications prefer their temporary files to have certain 
favorite initial letter sequences in their names. Use the pfx 
argument for this. This argument may be NULL or point to a 
string of up to five characters to be used as the first few char- 
acters of the temporary-file name. 

Tempnam uses malloc (3C) to get space for the constructed 
file name, and returns a pointer to this area. Thus, any 
pointer value returned from tempnam may serve as an argu- 
ment to free [see malloc (3C)]. If tempnam cannot return the 
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expected result for any reason, i.e. malloc (3C) failed, or none 
of the above mentioned attempts to find an appropriate direc- 
tory was successful, a NULL pointer will be returned. 

NOTES 

These functions generate a different file name each time they 
are called. 

Files created using these functions and either fopen (3S) or 
creat{2) are temporary only in the sense that they reside in a 
directory intended for temporary use, and their names are 
unique. It is the user's responsibility to use unlink {2) to 
remove the file when its use is ended. 

SEE ALSO 

creat(2), unlink(2), fopen(3S), malloc(3C), mktemp(3C), 
tmpfile(3S). 

CAVEATS 

If called more than 17,576 times in a single process, these 
functions will start recycling previously used names. 

Between the time a file name is created and the file is opened, 
it is possible for some other process to create a file with the 
same name. This can never happen if that other process is 
using these functions or mktemp, and the file names are 
chosen to render duplication by other means unlikely. 
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NAME 

tsearch, tfind, tdelete, twalk - manage binary search trees 

SYNOPSIS 

#include < search. h> 

char *tsearch ((char *) key, (char **) rootp, compar) 
int (*compar)( ); 

char *tfind ((char *) key, (char **) rootp, compar) 
int (*compar)( ); 

char *tdelete ((char *) key, (char **) rootp, compar) 
int (*compar)( ); 

void twalk ((char *) root, action) 
void (*action)( ); 

DESCRIPTION 

tsearch, tfind, tdelete, and twalk are routines for manipulating 
binary search trees. They are generalized from Knuth (6.2.2) 
Algorithms T and D. All comparisons are done with a user- 
supplied routine. This routine is called with two arguments, 
the pointers to the elements being compared. It returns an 
integer less than, equal to, or greater than 0, according to 
whether the first argument is to be considered less than, equal 
to or greater than the second argument. The comparison 
function need not compare every byte, so arbitrary data may 
be contained in the elements in addition to the values being 
compared. 

tsearch is used to build and access the tree. Key is a pointer 
to a datum to be accessed or stored. If there is a datum in 
the tree equal to *key (the value pointed to by key), a pointer 
to this found datum is returned. Otherwise, *key is inserted, 
and a pointer to it returned. Only pointers are copied, so the 
calling routine must store the data. Rootp points to a variable 
that points to the root of the tree. A NULL value for the vari- 
able pointed to by rootp denotes an empty tree; in this case, 
the variable will be set to point to the datum which will be at 
the root of the new tree. 

Like tsearch, tfind will search for a datum in the tree, returning 
a pointer to it if found. However, if it is not found, tfind will 
return a NULL pointer. The arguments for tfind are the same 
as for tsearch . 
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Tdelete deletes a node from a binary search tree. The argu- 
ments are the same as for tsearch. The variable pointed to by 
rootp will be changed if the deleted node was the root of the 
tree. Tdelete returns a pointer to the parent of the deleted 
node, or a NULL pointer if the node is not found. 

Twalk traverses a binary search tree. Root is the root of the 
tree to be traversed. (Any node in a tree may be used as the 
root for a walk below that node.) Action is the name of a rou- 
tine to be invoked at each node. This routine is, in turn, called 
with three arguments. The first argument is the address of 
the node being visited. 

The second argument is a value from an enumeration data 
type typedef enum { preorder, postorder, endorder, leaf } 
VISIT; (defined in the <search.h> header file), depending on 
whether this is the first, second or third time that the node has 
been visited (during a depth-first, left-to-right traversal of the 
tree), or whether the node is a leaf. The third argument is the 
level of the node in the tree, with the root being level zero. 

The pointers to the key and the root of the tree should be of 
type pointer-to-element, and cast to type pointer-to-character. 
Similarly, although declared as type pointer-to-character, the 
value returned should be cast into type pointer-to-element. 



The following code reads in strings and stores structures con- 
taining a pointer to each string and a count of its length. It 
then walks the tree, printing out the stored strings and their 
lengths in alphabetical order. 

#include <search.h> 
^include <stdio.h> 

struct node \ /* pointers to these are 



EXAMPLE 



stored in the tree */ 



char *string; 



int length; 

I; 

char string_space[ 10000]; 
struct node nodes[500]; 
struct node *root = NULL; 



/* to store strings */ 
/* nodes to store */ 
/* points to the root */ 



main( ) 
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char *strptr = string_space; 
struct node *nodeptr = nodes; 
void print_node( ), twalk( ); 
int i = 0, node_compare( ); 



while (gets(strptr) != NULL && i++ < 500) \ 
/* set node */ 
nodeptr->string = strptr; 
nodeptr->length = strl en (strptr); 
/* put node into the tree */ 
(void) tsearch((char *)nodeptr, (char **) &root, 

node_compare ) ; 
/* adjust pointers, so we don't overwrite tree */ 
strptr += nodeptr-> length + 1; 
nodeptr++; 

I 

twalk((char *)root, print_node); 

I 

/* 

This routine compares two nodes, based on an 
alphabetical ordering of the string field. 

*/ 
int 

node_compare(nodel, node2) 
char *node1, *node2; 
\ 

return strcmp(( (struct node *)node1 )->string, 
((struct node *) node2)->string); 

I 

/* 

This routine prints out a node, the first time 
twalk encounters it. 

V 

void 

print_node(node, order, level) 

char **node; 

VISIT order; 

int level; 

\ 

if (order = preorder || or order = leaf) \ 
(void)printf("string = %20s, length = %d\n", 
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(*( (struct node **)node) )->string, 
(*( (struct node **)node) )-> length); 

I 

I 

SEE ALSO 

bsearch(3C), hsearch(3C), lsearch(3C). 

DIAGNOSTICS 

A NULL pointer is returned by tsearch if there is not enough 
space available to create a new node. 

A NULL pointer is returned by tfind and tdelete if rootp is 
NULL on entry. 

If the datum is found, both tsearch and tfind return a pointer 
to it. If not, tfind returns NULL, and tsearch returns a pointer 
to the inserted item. 

WARNINGS 

The root argument to twalk is one level of indirection less than 
the rootp arguments to tsearch and tdelete. 
There are two nomenclatures used to refer to the order in 
which tree nodes are visited, tsearch uses preorder, pos- 
torder and endorder to respectively refer to visting a node 
before any of its children, after its left child and before its 
right, and after both its children. The alternate nomenclature 
uses preorder, inorder and postorder to refer to the same 
visits, which could result in some confusion over the meaning 
of postorder. 

CAVEAT 

If the calling function alters the pointer to the root, results are 
unpredictable. 



Page 4 



UP-13712 



TTYNAME(3C) 



NAME 

ttyname, isatty - find name of a terminal 

SYNOPSIS 

char *ttyname (fildes) 
int fildes; 

int isatty (fildes) 
int fildes; 

DESCRIPTION 

ttyname returns a pointer to a string containing the null- 
terminated path name of the terminal device associated with 
file descriptor fitdes. 

Isatty returns 1 if fildes is associated with a terminal device, 0 
otherwise. 

FILES 

/dev/* 

DIAGNOSTICS 

ttyname returns a NULL pointer if fildes does not describe a 
terminal device in directory /dev. 

CAVEAT 

The return value points to static data whose content is 
overwritten by each caH. 
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NAME 

ttyslot - find the slot in the utmp file of the current user 

SYNOPSIS 

int ttyslot ( ) 

DESCRIPTION 

ttyslot returns the index of the current user's entry in the 
/etc/ utmp file. This is accomplished by actually scanning the 
file /etc/inittab for the name of the terminal associated with 
the standard input, the standard output, or the error output 
(0, 1 or 2). 

FILES 

/etc/inittab 
/etc/utmp 

SEE ALSO 

getut(3C), ttyname(3C). 

DIAGNOSTICS 

A value of 0 is returned if an error was encountered while 
searching for the terminal name or if none of the above file 
descriptors is associated with a terminal device. 
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NAME 

ungetc - push character back into input stream 

SYNOPSIS 

#include <stdio.h> 

int ungetc (c, stream) 
int c; 

FILE *stream; 
DESCRIPTION 

ungetc inserts the character c into the buffer associated with 
an input stream. That character, c, will be returned by the 
next getc (3S) call on that stream, ungetc returns c, and 
leaves the file stream unchanged. 

One character of pushback is guaranteed, provided something 
has already been read from the stream and the stream is 
actually buffered. 

If c equals EOF, ungetc does nothing to the buffer and 
returns EOF. 

Fseek (3S) erases all memory of inserted characters. 

SEE ALSO 

fseek (3S), getc(3S), setbuf(3S), stdio(3S). 

DIAGNOSTICS 

ungetc returns EOF if it cannot insert the character. 

BUGS 

When stream is stdin, one character may be pushed back 
onto the buffer without a previous read statement. 
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NAME 

vprintf, vfprintf, vsprintf - print formatted output of a varargs 
argument list 

SYNOPSIS 

#include <stdio.h> 
#include < varargs. h> 

int vprintf (format, ap) 
char *format; 
vajist ap; 

int vfprintf (stream, format, ap) 
FILE *stream; 
char *format; 
vajist ap; 

int vsprintf (s, format, ap) 
char *s, *format; 
vajist ap; 

DESCRIPTION 

vprintf, vfprintf, and vsprintf are the same as printf, fprintf, 
and sprintf respectively, except that instead of being called 
with a variable number of arguments, they are called with an 
argument list as defined by varargs {5). 

EXAMPLE 

The following demonstrates the use of vfprintf to write an error 
routine. 

^include <stdio.h> 
^include <varargs.h> 



/* 

* error should be called like 

* error (function_name, format, argl, arg2...); */ 
/*VARARGS*/ 

void 

error ( va_a 1 i st) 

/* Note that the function_name and format arguments 

* cannot be separately declared because of the 

* definition of varargs. */ 



UP-13712 



Page 1 



VPRINTF(3S) 



va_l ist args; 
char *fmt; 

va_start(args); 

/* print out name of function causing error */ 
(void)fprintf(stderr, "ERROR in %s: 
va_arg(args, char *)); 
fmt = va_arg(args, char *); 
/* print out remainder of message */ 
(void)vfprintf (stderr, fmt, args); 
va_end(args); 
(void)abort( ); 
I 

SEE ALSO 

printf(3S), varargs(5). 



va_dcl 
I 
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NAME 

bessel: jO, j1, jn, yO, y1, yn - Bessel functions 
SYNOPSIS 



#include <math.h> 


double 


jO (x) 


double 


x; 


double 


ii (x) 


double 


x; 


double 


jn (n, x) 


int n; 




double 


x; 


double 


yO (x) 


double 


x; 


double 


y1 (x) 


double 


x; 


double 


yn (n, x) 


int n; 




double 


x; 


DESCRIPTION 



JO and j1 return Bessel functions of x of the first kind of ord- 
ers 0 and 1 respectively. Jn returns the Bessel function of x 
of the first kind of order n. 

YO and y1 return Bessel functions of x of the second kind of 
orders 0 and 1 respectively. Yn returns the Bessel function of 
x of the second kind of order n. The value of x must be posi- 
tive. 

SEE ALSO 

matherr(3M). 

DIAGNOSTICS 

Non-positive arguments cause yO, y1 and yn to return the 
value -HUGE and to set errno to EDOM. In addition, a mes- 
sage indicating DOMAIN error is printed on the standard error 
output. 

Arguments too large in magnitude cause jO, j1 , yO and y1 to 
return zero and to set errno to ERANGE. In addition, a mes- 
sage indicating TLOSS error is printed on the standard error 
output. 
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These error-handling procedures may be changed with the 
function matherr (3M). 
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NAME 



erf, erfc — error function and complementary error function 

SYNOPSIS 

#include <math.h> 

double erf (x) 
double x; 

double erfc (x) 
double x; 



DESCRIPTION 2 *f 

erf returns the error function of x, defined as — = I e~ f2 dt. 



erfc, which returns 1.0 — erf(x), is provided because of the 
extreme loss of relative accuracy if erf(x) is called for large x and 
the result subtracted from 1.0 (e.g., for x = 5, 12 places are 
lost). 

SEE ALSO 

exp(3M). 
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NAME 

exp, log, Iog10, pow, sqrt - exponential, logarithm, power, 
square root functions 

SYNOPSIS 

#include <math.h> 

double exp (x) 
double x; 

double log (x) 
double x; 

double Iog10 (x) 
double x; 

double pow (x, y) 
double x, y; 

double sqrt (x) 
double x; 

DESCRIPTION 

exp returns e x . 

Log returns the natural logarithm of x. The value of x must be 
positive. 

Log10 returns the logarithm base ten of x. The value of x 
must be positive. 

Pow returns x^. If x is zero, y must be positive. If x is nega- 
tive, y must be an integer. 

Sqrt returns the non-negative square root of x. The value of x 
may not be negative. 

SEE ALSO 

hypot(3M), matherr(3M), sinh(3M). 

DIAGNOSTICS 

exp returns HUGE when the correct value would overflow, or 
0 when the correct value would underflow, and sets errno to 
ERANGE. 

Log and Iog10 return -HUGE and set errno to EDOM when x 
is non-positive. A message indicating DOMAIN error (or SING 
error when x is 0) is printed on the standard error output. 
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Pow returns 0 and sets errno to EDOM when x is 0 and y is 
non-positive, or when x is negative and y is not an integer. In 
these cases a message indicating DOMAIN error is printed on 
the standard error output. When the correct value for pow 
would overflow or underflow, pow returns ±HUGE or 0 
respectively, and sets errno to ERANGE. 

Sqrt returns 0 and sets errno to EDOM when x is negative. A 
message indicating DOMAIN error is printed on the standard 
error output. 

These error-handling procedures may be changed with the 
function matherr(3M). 
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NAME 

floor, ceil, fmod, fabs - floor, ceiling, remainder, absolute value 
functions 

SYNOPSIS 

#include <math.h> 

double floor (x) 
double x; 

double ceil (x) 
double x; 

double fmod (x, y) 
double x, y; 

double fabs (x) 
double x; 

DESCRIPTION 

floor returns the largest integer (as a double-precision 
number) not greater than x. 

Ceil returns the smallest integer not less than x. 

Fmod returns the floating-point remainder of the division of x 
by y: zero if y is zero or if x/y would overflow; otherwise the 
number f with the same sign as x, such that x = iy + f for 
some integer /, and | f \ < | y J . 

Fabs returns the absolute value of x, | x J . 

SEE ALSO 

abs(3C). 
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NAME 

gamma — log gamma function 

SYNOPSIS 

#include <math.h> 

double gamma (x) 
double x; 

extern int signgam; 



DESCRIPTION | 

gamma returns ln(|r(x)|), where T(x) is defined as I e^F^dt. 



The sign of T(x) is returned in the external integer signgam. The 
argument x may not be a non-positive integer. 

The following C program fragment might be used to calculate Y: 

if ((y = gamma(x)) > LN MAXDOUBLE) 

error( ); 
y = signgam * exp(y); 

where LN MAXDOUBLE is the least value that causes exp(3M) 

to return a range error, and is defined in the <values.h> header 



SEE ALSO 

exp(3M), matherr(3M), values(5). 

DIAGNOSTICS 

For non-negative integer arguments HUGE is returned, and errno 
is set to EDOM. A message indicating SING error is printed on 
the standard error output. 

If the correct value would overflow, gamma returns HUGE and 
sets errno to ERANGE. 

These error-handling procedures may be changed with the 
function mathern[3M). 




o 



file. 
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NAME 

hypot - Euclidean distance function 

SYNOPSIS 

#include <math.h> 

double hypot (x, y) 
double x, y; 

DESCRIPTION 

hypot returns 

sqrt(x * x + y * y), 
taking precautions against unwarranted overflows. 

SEE ALSO 

matherr(3M). 

DIAGNOSTICS 

When the correct value would overflow, hypot returns HUGE 
and sets errno to ERANGE. 

These error-handling procedures may be changed with the 
function matherr{3M). 



UP-13712 



Page 1 



HYPOT(3M) 



[This page left blank.] 



Page 2 



UP-13712 



MATHERR (3M) 



NAME 

matherr - error-handling function 

SYNOPSIS 

#include <math.h> 

int matherr (x) 
struct exception *x; 

DESCRIPTION 

matherr is invoked by functions in the Math Library when 
errors are detected. Users may define their own procedures 
for handling errors, by including a function named matherr in 
their programs, matherr must be of the form described 
above. When an error occurs, a pointer to the exception 
structure x will be passed to the user-supplied matherr func- 
tion. This structure, which is defined in the <math.h> header 
file, is as follows: 

struct exception { 
int type; 
char *name; 

double arg1, arg2, retval; 

}; 

The element type is an integer describing the type of error 
that has occurred, from the following list of constants (defined 
in the header file): 

DOMAIN argument domain error 

SING argument singularity 

OVERFLOW overflow range error 

UNDERFLOW underflow range error 

TLOSS total loss of significance 

PLOSS partial loss of significance 

The element name points to a string containing the name of 
the function that incurred the error. The variables arg1 and 
arg2 are the arguments with which the function was invoked. 
Retval is set to the default value that will be returned by the 
function unless the user's matherr sets it to a different value. 

If the user's matherr function returns non-zero, no error mes- 
sage will be printed, and errno will not be set. 

If matherr is not supplied by the user, the default error- 
handling procedures, described with the math functions 
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involved, will be invoked upon error. These procedures are 
also summarized in the table below. In every case, errno is 
set to EDOM or ERANGE and the program continues. 

EXAMPLE 

^include <math.h> 



int 

matherr(x) 

register struct exception *x; 
I 

switch (x->type) { 
case DOMAIN: 

/* change sqrt to return sqrt(-argl), not 0 */ 
if ( !strcmp(x->name, "sqrt")) { 

x->retval = sqrt(-x->arg1 ); 
return (0); /* print message and 
set errno */ 

i 

case SING: 

/* all other domain or sing errors, 

print message and abort */ 
fprintf (stderr, "domain error in %s\n", x->name); 
abort ( ); 
case PLOSS: 

/* print detailed error message */ 
fprintf (stderr, "loss of significance 
in %s(%g) = %g\n", 
x->name, x->arg1, x->retval); 
return (1); /* take no other action */ 

I 

return (0); /* all other errors, execute default 
procedure */ 

i 
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DEFAULT ERROR HANDLING PROCEDURES 




Types of Errors 


iwnp 


JOMAIrs 


SING 


OVERrLOW 


UNDERFLOW 


TLOSS 


PLOSS 


errno 


EDOM 


EDOIV 


ERANGE 


ERANGE 


ERANGE 


ERANGE 


BESSEL: 


■ 


• 


- 


- 


M, 0 


* 


yO, y1 , yn (arg ^ 0) 


M, -H 


• 


■ 


- 




* 


EXP: 


- 


- 


H 


0 


- 


- 


LOG, LOG 10: 














(arg < 0) 


M, -H 












(arg = 0) 




m, n 
















-+- u 
— n 


U 






neg ** non-int 


M, 0 












0 ** non-pos 














SORT: 


M, 0 












GAMMA: 




M, H 


H 








HYPOT: 






H 








SINH: 






±H 








COSH: 






H 








SIN, COS, TAN: - 








M, 0 


* 




ASIN, ACQS, ATAN2: M, 0 

















ABBREVIATIONS 


* 


As much as possible of the value is returned. 


M 


Message is printed (EDOM error). 


H 


HUGE is returned. 


-H 


-HUGE is returned. 


±H 


HUGE or -HUGE is returned. 


0 


0 is returned 
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NAME 

sinh, cosh, tanh - hyperbolic functions 

SYNOPSIS 

#include <math.h> 

double sinh (x) 
double x; 

double cosh (x) 
double x; 

double tanh (x) 
double x; 

DESCRIPTION 

sinh, cosh, and tanh return, respectively, the hyberbolic sine, 
cosine and tangent of their argument. 

SEE ALSO 

matherr(3M). 

DIAGNOSTICS 

sinh and cosh return HUGE (and sinh may return -HUGE for 
negative x) when the correct value would overflow and set 
errno to ERANGE. 

These error-handling procedures may be changed with the 
function matherr(3M). 



UP-13712 



Page 1 



SINH(3M) 



[This page left blank.] 



Page 2 



UP-13712 



TRIG (3M) 



NAME 

trig: sin, cos, tan, asin, acos, atan, atan2 - trigonometric func- 
tions 

SYNOPSIS 



#include <math.h> 


double 


sin (x) 


double 


x; 


double 


cos (x) 


double 


x; 


double 


tan (x) 


double 


x; 


double 


asin (x) 


double 


x; 


double 


acos (x) 


double 


x; 


double 


atan (x) 


double 


x; 


double 


atan2 (y, x) 


double 


y> x; 


DESCRIPTION 



Sin, cos and tan return respectively the sine, cosine and 
tangent of their argument, x, measured in radians. 

Asin returns the arcsine of x, in the range [-ir/2,ir/2]. 

Acos returns the arccosine of x, in the range [O.ir]. 

Atan returns the arctangent of x, in the range [-ir/2,ir/2]. 

Atan2 returns the arctangent of y/x, in the range (-tt.tt], using 
the signs of both arguments to determine the quadrant of the 
return value. 

SEE ALSO 

matherr(3M). 

DIAGNOSTICS 

Sin, cos, and tan lose accuracy when their argument is far 
from zero. For arguments sufficiently large, these functions 
return zero when there would otherwise be a complete loss of 
significance. In this case a message indicating TLOSS error is 
printed on the standard error output. For less extreme 
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arguments causing partial loss of significance, a PLOSS error 
is generated but no message is printed. In both cases, errno 
is set to ERANGE. 

If the magnitude of the argument of asin or acos is greater 
than one, or if both arguments of atan2 are zero, zero is 
returned and errno is set to EDOM. In addition, a message 
indicating DOMAIN error is printed on the standard error out- 
put. 

These error-handling procedures may be changed with the 
function matherr(3M). 
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NAME 

t_accept - accept a connect request 

SYNOPSIS 

#include <tiuser.h> 

int t_accept(fd, resfd, call) 

int fd; 

int resfd; 

struct t call *call; 

DESCRIPTION 

This function is issued by a transport user to accept a connect 
request. Fd identifies the local transport endpoint where the 
connect indication arrived, resfd specifies the local transport 
endpoint where the connection is to be established, and call 
contains information required by the transport provider to 
complete the connection. Call points to a t_call structure 
which contains the following members: 

struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 
int sequence; 

Netbuf is described in intro(3). In call, addr is the address of 
the caller, opt indicates any protocol-specific parameters asso- 
ciated with the connection, udata points to any user data to 
be returned to the caller, and sequence is the value returned 
by tjisten that uniquely associates the response with a previ- 
ously received connect indication. 

A transport user may accept a connection on either the same, 
or on a different, local transport endpoint than the one on 
which the connect indication arrived. If the same endpoint is 
specified (i.e., resfd =fd), the connection can be accepted 
unless the following condition is true: The user has received 
other indications on that endpoint but has not responded to 
them (with t_accept or tjsnddis). For this condition, t_accept 
will fail and set tjerrno to TBADF. 

If a different transport endpoint is specified (resfd\=fd), the 
endpoint must be bound to a protocol address and must be in 
the TJDLE state [see t_getstate (3N)] before the t_accept is 
issued. 
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For both types of endpoints, t_accept will fail and set t_errno 
to TLOOK if there are indications (e.g., a connect or discon- 
nect) waiting to be received on that endpoint. 

The values of parameters specified by opt and the syntax of 
those values are protocol specific. The udata argument 
enables the called transport user to send user data to the 
caller and the amount of user data must not exceed the limits 
supported by the transport provider as returned by topen or 
tjgetinfo. If the len [see netbuf in intro{3)] field of udata is 
zero, no data will be sent to the caller. 

On failure, tjerrno may be set to one of the following: 

[TBADF] The specified file descriptor does not 

refer to a transport endpoint, or the user 
is illegally accepting a connection on the 
same transport endpoint on which the 
connect indication arrived. 

[TOUTSTATE] The function was issued in the wrong 
sequence on the transport endpoint refer- 
enced by fd t or the transport endpoint 
referred to by resfd is not in the TJDLE 
state. 

The user does not have permission to 
accept a connection on the responding 
transport endpoint or use the specified 
options. 

The specified options were in an incorrect 
format or contained illegal information. 

The amount of user data specified was 
not within the bounds allowed by the 
transport provider. 

An invalid sequence number was speci- 
fied. 

An asynchronous event has occurred on 
the transport endpoint referenced by fd 
and requires immediate attention. 

[TNOTSUPPORT] This function is not supported by the 
underlying transport provider. 



[TACCES] 

[TBADOPT] 
[TBADDATA] 

[TBADSEQ] 
[TLOOK] 
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[TSYSERR] A system error has occurred during exe- 

cution of this function. 

SEE ALSO 

intro(3), t_connect(3N), t_getstate(3N), t_listen(3N), 
t_open(3N), t_rcvconnect(3N). 
Network Programmer's Guide 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Other- 
wise, a value of -1 is returned and tjerrno is set to indicate the 
error. 
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NAME 

t alloc - allocate a library structure 

SYNOPSIS 

#include <tiuser.h> 

char *t_alloc(fd, struct type, fields) 
int fd; 

int struct type; 
int fields; 

DESCRIPTION 

The t_alloc function dynamically allocates memory for the vari- 
ous transport function argument structures as specified below. 
This function will allocate memory for the specified structure, 
and will also allocate memory for buffers referenced by the 
structure. 

The structure to allocate is specified by struct Jype, and can 
be one of the following: 

T_BIND struct t_bind 

T_CALL struct t call 

T_OPTMGMT struct t_optmgmt 

T_DIS struct t_discon 

T_UNITDATA struct t_unitdata 

T_UD ERROR struct t_uderr 

TJNFO struct tjnfo 

where each of these structures may subsequently be used as 
an argument to one or more transport functions. 

Each of the above structures, except TJNFO, contains at least 
one field of type struct netbuf. Netbuf is described in intro(3). 
For each field of this type, the user may specify that the 
buffer for that field should be allocated as well. The fields 
argument specifies this option, where the argument is the 
bitwise-OR of any of the following: 

T ADDR The addr field of the t_bind, t_call, t unitdata, or 
t_uderr structures. 

T_OPT The opt field of the t_optmgmt, t_call, tjunitdata, or 
t uderr structures. 
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T_UDATA The udata field of the t_call, t_discon, or t_unitdata 
structures. 

T_ALL All relevant fields of the given structure. 

For each field specified in fields, t_alloc will allocate memory 
for the buffer associated with the field, and initialize the buf 
pointer and maxlen [see netbuf in intro(3) for description of buf 
and maxlen] field accordingly. The length of the buffer allo- 
cated will be based on the same size information that is 
returned to the user on t_open and t getinfo. Thus, fd must 
refer to the transport endpoint through which the newly allo- 
cated structure will be passed, so that the appropriate size 
information can be accessed. If the size value associated with 
any specified field is -1 or -2 (see t_open or tjgetinfo), t_alloc 
will be unable to determine the size of the buffer to allocate 
and will fail, setting tjsrrno to TSYSERR and errno to EINVAL. 
For any field not specified in fields, buf will be set to NULL 
and maxlen will be set to zero. 

Use of t_alloc to allocate structures will help ensure the com- 
patibility of user programs with future releases of the tran- 
sport interface. 

On failure, tjermo may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to 

a transport endpoint. 

[TSYSERR] A system error has occurred during execution 
of this function. 

SEE ALSO 

intro(3), t_free(3N), t_getinfo(3N), t_open(3N). 
Network Programmer's Guide 

DIAGNOSTICS 

On successful completion, t_alloc returns a pointer to the 
newly allocated structure. On failure, NULL is returned. 
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NAME 

t_bind - bind an address to a transport endpoint 

SYNOPSIS 

#include <tiuser.h> 

int t bind(fd, req, ret) 
int fd; 

struct t bind *req; 

struct t_bind *ret; 

DESCRIPTION 

This function associates a protocol address with the transport 
endpoint specified by fd and activates that transport endpoint. 
In connection mode, the transport provider may begin accept- 
ing or requesting connections on the transport endpoint. In 
connectionless mode, the transport user may send or receive 
data units through the transport endpoint. 

The req and ret arguments point to a t_bind structure contain- 
ing the following members: 

struct netbuf addr; 
unsigned qlen; 

Netbuf is described in intro(3). The addr field of the t_bind 
structure specifies a protocol address and the qlen field is 
used to indicate the maximum number of outstanding connect 
indications. 

f?eqr is used to request that an address, represented by the 
netbuf structure, be bound to the given transport endpoint. 
Len [see netbuf in intro{3); also for buf and maxlen] specifies 
the number of bytes in the address and buf points to the 
address buffer. Maxlen has no meaning for the req argument. 
On return, ret contains the address that the transport provider 
actually bound to the transport endpoint; this may be different 
from the address specified by the user in req. In ret, the user 
specifies maxlen which is the maximum size of the address 
buffer and buf which points to the buffer where the address is 
to be placed. On return, len specifies the number of bytes in 
the bound address and buf points to the bound address. If 
maxlen is not large enough to hold the returned address, an 
error will result. 
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If the requested address is not available, or if no address is 
specified in req (the len field of addr in req is zero) the tran- 
sport provider will assign an appropriate address to be bound, 
and will return that address in the addr field of ret. The user 
can compare the addresses in req and ret to determine 
whether the transport provider bound the transport endpoint 
to a different address than that requested. 

Req may be NULL if the user does not wish to specify an 
address to be bound. Here, the value of qlen is assumed to 
be zero, and the transport provider must assign an address to 
the transport endpoint. Similarly, ret may be NULL if the user 
does not care what address was bound by the provider and is 
not interested in the negotiated value of qlen. It is valid to set 
req and ret to NULL for the same call, in which case the pro- 
vider chooses the address to bind to the transport endpoint 
and does not return that information to the user. 

The qlen field has meaning only when initializing a 
connection-mode service. It specifies the number of outstand- 
ing connect indications the transport provider should support 
for the given transport endpoint. An outstanding connect indi- 
cation is one that has been passed to the transport user by 
the transport provider. A value of qlen greater than zero is 
only meaningful when issued by a passive transport user that 
expects other users to call it. The value of qlen will be nego- 
tiated by the transport provider and may be changed if the 
transport provider cannot support the specified number of 
outstanding connect indications. On return, the qlen field in 
ret will contain the negotiated value. 

This function allows more than one transport endpoint to be 
bound to the same protocol address (however, the transport 
provider must support this capability also), but it is not allow- 
able to bind more than one protocol address to the same tran- 
sport endpoint. If a user binds more than one transport end- 
point to the same protocol address, only one endpoint can be 
used to listen for connect indications associated with that pro- 
tocol address. In other words, only one t_bind for a given pro- 
tocol address may specify a value of qlen greater than zero. 
In this way, the transport provider can identify which transport 
endpoint should be notified of an incoming connect indication. 
If a user attempts to bind a protocol address to a second 
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transport endpoint with a value of qlen greater than zero, the 
transport provider will assign another address to be bound to 
that endpoint. If a user accepts a connection on the transport 
endpoint that is being used as the listening endpoint, the 
bound protocol address will be found to be busy for the dura- 
tion of that connection. No other transport endpoints may be 
bound for listening while that initial listening endpoint is in the 
data transfer phase. This will prevent more than one transport 
endpoint bound to the same protocol address from accepting 
connect indications. 

On failure, t_errno may be set to one of the following: 



[TBADF] 

[TOUTSTATE] 

[TBADADDR] 

[TNOADDR] 

[TACCES] 

[TBUFOVFLW] 



[TSYSERR] 



The specified file descriptor does not 
refer to a transport endpoint. 

The function was issued in the wrong 
sequence. 

The specified protocol address was in an 
incorrect format or contained illegal infor- 
mation. 

The transport provider could not allocate 
an address. 

The user does not have permission to use 
the specified address. 

The number of bytes allowed for an 
incoming argument is not sufficient to 
store the value of that argument. The 
provider's state will change to TJDLE and 
the information to be returned in ret will 
be discarded. 

A system error has occurred during exe- 
cution of this function. 



SEE ALSO 

intro(3), t_open(3N), t_optmgmt(3N), t_unbind(3N). 
Network Programmer's Guide 

DIAGNOSTICS 

t_bind returns 0 on success and -1 on failure and t_errno is set 
to indicate the error. 
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NAME 

t_close - close a transport endpoint 

SYNOPSIS 

#include <tiuser.h> 

int t close(fd) 
int fd; 

DESCRIPTION 

The t_close function informs the transport provider that the 
user is finished with the transport endpoint specified by fd, 
and frees any local library resources associated with the end- 
point. In addition, t_close closes the file associated with the 
transport endpoint. 

t_close should be called from the T_UNBND state [see 
t_getstate (3N)]. However, this function does not check state 
information, so it may be called from any state to close a tran- 
sport endpoint. If this occurs, the local library resources asso- 
ciated with the endpoint will be freed automatically. In addi- 
tion, c/ose(2) will be issued for that file descriptor; the close 
will be abortive if no other process has that file open, and will 
break any transport connection that may be associated with 
that endpoint. 

On failure, tjerrno may be set to the following: 

[TBADF] The specified file descriptor does not refer to a 
transport endpoint. 

SEE ALSO 

t_getstate(3N), t_open(3N), t_unbind(3N). 
Network Programmer's Guide 

DIAGNOSTICS 

t_close returns 0 on success and -1 on failure and tjerrno is 
set to indicate the error. 



UP-13712 



Page 1 



T_CLOSE(3N) 



[This page left blank.] 



Page 2 



UP-13712 



T_CONNECT(3N) 



NAME 

t_connect - establish a connection with another transport user 

SYNOPSIS 

#include <tiuser.h> 

int t_connect(fd, sndcall, rcvcall) 
int fd; 

struct t call *sndcall; 
struct t_call *rcvcall; 

DESCRIPTION 

This function enables a transport user to request a connection 
to the specified destination transport user. Fd identifies the 
local transport endpoint where communication will be esta- 
blished, while sndcall and rcvcall point to a t_call structure 
which contains the following members: 



struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 
int sequence; 



Sndcall specifies information needed by the transport provider 
to establish a connection and rcvcall specifies information that 
is associated with the newly established connection. 

Netbuf is described in intro{3). In sndcall, addr specifies the 
protocol address of the destination transport user, opt 
presents any protocol-specific information that might be 
needed by the transport provider, udata points to optional 
user data that may be passed to the destination transport 
user during connection establishment, and sequence has no 
meaning for this function. 

On return in rcvcall, addr returns the protocol address associ- 
ated with the responding transport endpoint, opt presents any 
protocol-specific information associated with the connection, 
udata points to optional user data that may be returned by 
the destination transport user during connection establish- 
ment, and sequence has no meaning for this function. 

The opt argument implies no structure on the options that 
may be passed to the transport provider. The transport pro- 
vider is free to specify the structure of any options passed to 
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it. These options are specific to the underlying protocol of the 
transport provider. The user may choose not to negotiate 
protocol options by setting the len field of opt to zero. In this 
case, the provider may use default options. 

The udata argument enables the caller to pass user data to 
the destination transport user and receive user data from the 
destination user during connection establishment. However, 
the amount of user data must not exceed the limits supported 
by the transport provider as returned by t_open (3N) or 
t getinfo (3N). If the len [see netbuf in intro(3)] field of udata 
is zero in sndcall, no data will be sent to the destination tran- 
sport user. 

On return, the addr, opt, and udata fields of rcvcall will be 
updated to reflect values associated with the connection. 
Thus, the maxlen [see netbuf in intro{3)] field of each argu- 
ment must be set before issuing this function to indicate the 
maximum size of the buffer for each. However, rcvcall may 
be NULL, in which case no information is given to the user on 
return from t_connect. 

By default, t_connect executes in synchronous mode, and will 
wait for the destination user's response before returning con- 
trol to the local user. A successful return (i.e. return value of 
zero) indicates that the requested connection has been esta- 
blished. However, if 0_NDELAY is set (via t_open or fcntl), 
t connect executes in asynchronous mode. In this case, the 
call will not wait for the remote user's response, but will return 
control immediately to the local user and return -1 with tjerrno 
set to TNODATA to indicate that the connection has not yet 
been established. In this way, the function simply initiates the 
connection establishment procedure by sending a connect 
request to the destination transport user. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not 

refer to a transport endpoint. 

[TOUTSTATE] The function was issued in the wrong 
sequence. 

[TNODATA] O NDELAY was set, so the function suc- 

cessfully initiated the connection estab- 
lishment procedure, but did not wait for a 
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[TBADADDR] 

[TBADOPT] 

[TBADDATA] 

[TACCES] 
[TBUFOVFLW] 



[TLOOK] 

[TNOTSUPPORT] 
[TSYSERR] 



response from the remote user. 

The specified protocol address was in an 
incorrect format or contained illegal infor- 
mation. 

The specified protocol options were in an 
incorrect format or contained illegal infor- 
mation. 

The amount of user data specified was 
not within the bounds allowed by the 
transport provider. 

The user does not have permission to use 
the specified address or options. 

The number of bytes allocated for an 
incoming argument is not sufficient to 
store the value of that argument. If exe- 
cuted in synchronous mode, the 
provider's state, as seen by the user, 
changes to T_DATAXFER, and the con- 
nect indication information to be returned 
in rcvcall is discarded. 

An asynchronous event has occurred on 
this transport endpoint and requires 
immediate attention. 

This function is not supported by the 
underlying transport provider. 

A system error has occurred during exe- 
cution of this function. 



SEE ALSO 

intro(3), t_accept(3N), t_getinfo(3N), t_listen(3N), t_open(3N), 
t_optmgmt (3N) , t_rcvconnect (3N) . 
Network Programmer's Guide 

DIAGNOSTICS 

t_connect returns 0 on success and -1 on failure and t_errno is 
set to indicate the error. 
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NAME 

t_error - produce error message 

SYNOPSIS 

#include <tiuser.h> 

void t_error(errmsg) 
char *errmsg; 
extern int terrno; 
extern char *t_errlist[]; 
extern int t_nerr; 

DESCRIPTION 

The tjerror function produces a message on the standard 
error output which describes the last error encountered during 
a call to a transport function. The argument string errmsg is a 
user-supplied error message that gives context to the error. 
tjsrror prints the user-supplied error message followed by a 
colon and a standard error message for the current error 
defined in t_errno. To simplify variant formatting of mes- 
sages, the array of message strings tjerrlist is provided; 
tjerrno can be used as an index in this table to get the mes- 
sage string without the newline. Tjierr is the largest message 
number provided for in the t errlist table. 

T_errno is only set when an error occurs and is not cleared on 
successful calls. 

EXAMPLE 

If a t_connect function fails on transport endpoint fd2 because 
a bad address was given, the following call might follow the 
failure: 

t_error("t_connect failed on fd2"); 
The diagnostic message to be printed would look like: 

t_connect failed on fd2: Incorrect transport address 

format 

where "Incorrect transport address format" identifies the 
specific error that occurred, and "t connect failed on fd2" tells 
the user which function failed on which transport endpoint. 
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NAME 

t_free - free a library structure 

SYNOPSIS 

#include <tiuser.h> 

int t_free(ptr, structtype) 

char *ptr; 

int struct type; 

DESCRIPTION 

The tjree function frees memory previously allocated by 
t_alloc. This function will free memory for the specified struc- 
ture, and will also free memory for buffers referenced by the 
structure. 

Ptr points to one of the six structure types described for 
t_alloc, and struct Jype identifies the type of that structure 
which can be one of the following: 



T 


BIND 


struct t_bind 


T 


CALL 


struct t_call 


T 


OPTMGMT 


struct t_optmgmt 


T 


DIS 


struct t_discon 


T 


UNITDATA 


struct t_unitdata 


T 


.UDERROR 


struct t_uderr 


T 


.INFO 


struct tjnfo 



where each of these structures is used as an argument to one 
or more transport functions. 

tjree will check the addr, opt, and udata fields of the given 
structure (as appropriate), and free the buffers pointed to by 
the buf field of the netbuf [see intro(3)] structure. If buf is 
NULL, tjree will not attempt to free memory. After all buffers 
are freed, tjree will free the memory associated with the 
structure pointed to by ptr. 

Undefined results will occur if ptr or any of the buf pointers 
points to a block of memory that was not previously allocated 
by t_alloc. 

On failure, t_errno may be set to the following: 
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[TSYSERR] A system error has occurred during execution 
of this function. 

SEE ALSO 

intro(3), t_alloc(3N). 
Network Programmer's Guide 

DIAGNOSTICS 

tjree returns 0 on success and -1 on failure and tjerrno is set 
to indicate the error. 
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NAME 

tgetinfo - get protocol-specific service information 

SYNOPSIS 

#include <tiuser.h> 

int t_getinfo(fd, info) 
int fd; 

struct tinfo *info; 
DESCRIPTION 

This function returns the current characteristics of the underly- 
ing transport protocol associated with file descriptor fd. The 
info structure is used to return the same information returned 
by t_open. This function enables a transport user to access 
this information during any phase of communication. 

This argument points to a tjnfo structure which contains the 
following members: 

long addr; /* max size of the transport protocol address */ 
long options; /* max number of bytes of protocol -specific 
options */ 

long tsdu; /* max size of a transport service data unit 
(TSDU) */ 

long etsdu; /* max size of an expedited transport service 

data unit (ETSDU) */ 
long connect; /* max amount of data allowed on connection 

establishment functions */ 
long discon; /* max amount of data allowed on t_snddis 

and t_rcvdis functions */ 
long servtype; /* service type supported by the transport 

provider */ 



The values of the fields have the following meanings: 

addr A value greater than or equal to zero indicates 

the maximum size of a transport protocol 
address; a value of -1 specifies that there is no 
limit on the address size; and a value of -2 
specifies that the transport provider does not 
provide user access to transport protocol 
addresses. 
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options A value greater than or equal to zero indicates 

the maximum number of bytes of protocol- 
specific options supported by the provider; a 
value of -1 specifies that there is no limit on the 
option size; and a value of -2 specifies that the 
transport provider does not support user- 
settable options. 

tsdu A value greater than zero specifies the max- 

imum size of a transport service data unit 
(TSDU); a value of zero specifies that the tran- 
sport provider does not support the concept of 
TSDU, although it does support the sending of 
a data stream with no logical boundaries 
preserved across a connection; a value of -1 
specifies that there is no limit on the size of a 
TSDU; and a value of -2 specifies that the 
transfer of normal data is not supported by the 
transport provider. 

etsdu A value greater than zero specifies the max- 

imum size of an expedited transport service 
data unit (ETSDU); a value of zero specifies 
that the transport provider does not support 
the concept of ETSDU, although it does sup- 
port the sending of an expedited data stream 
with no logical boundaries preserved across a 
connection; a value of -1 specifies that there is 
no limit on the size of an ETSDU; and a value 
of -2 specifies that the transfer of expedited 
data is not supported by the transport pro- 
vider. 

connect A value greater than or equal to zero specifies 
the maximum amount of data that may be 
associated with connection establishment func- 
tions; a value of -1 specifies that there is no 
limit on the amount of data sent during con- 
nection establishment; and a value of -2 speci- 
fies that the transport provider does not allow 
data to be sent with connection establishment 
functions. 
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discon A value greater than or equal to zero specifies 

the maximum amount of data that may be 
associated with the tjsnddis and tjcvdis func- 
tions; a value of -1 specifies that there is no 
limit on the amount of data sent with these 
abortive release functions; and a value of -2 
specifies that the transport provider does not 
allow data to be sent with the abortive release 
functions. 

servtype This field specifies the service type supported 
by the transport provider, as described below. 

If a transport user is concerned with protocol independence, 
the above sizes may be accessed to determine how large the 
buffers must be to hold each piece of information. Alterna- 
tively, the t_alloc function may be used to allocate these 
buffers. An error will result if a transport user exceeds the 
allowed data size on any function. The value of each field 
may change as a result of option negotiation, and t_getinfo 
enables a user to retrieve the current characteristics. 

The servtype field of info may specify one of the following 
values on return: 

T_COTS The transport provider supports a 

connection-mode service but does not sup- 
port the optional orderly release facility. 

T_COTS_ORD The transport provider supports a 
connection-mode service with the optional 
orderly release facility. 

T_CLTS The transport provider supports a 

connectionless-mode service. For this service 
type, t_open will return -2 for etsdu, connect, 
and discon. 

On failure, t errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to 

a transport endpoint. 

[TSYSERR] A system error has occurred during execution 
of this function. 
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SEE ALSO 

t_open(3N). 

Network Programmer's Guide 
DIAGNOSTICS 

t_getinfo returns 0 on success and -1 on failure and tjerrno is 
set to indicate the error. 
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NAME 

t_getstate - get the current state 

SYNOPSIS 

#include <tiuser.h> 

int t getstate(fd) 
int fd; 

DESCRIPTION 

The t_getstate function returns the current state of the pro- 
vider associated with the transport endpoint specified by fd. 

On failure, t_errno may be set to one of the following: 

The specified file descriptor does not refer 
to a transport endpoint. 

The transport provider is undergoing a 
state change. 

A system error has occurred during execu- 
tion of this function. 



[TBADF] 

[TSTATECHNG] 

[TSYSERR] 



SEE ALSO 

t_open(3N). 

Network Programmer's Guide 

DIAGNOSTICS 

tjjetstate returns the current state on successful completion 
and -1 on failure and tjerrno is set to indicate the error. The 
current state may be one of the following: 

TJJNBND unbound 

TJDLE idle 

T_OUTCON outgoing connection pending 

TJNCON incoming connection pending 

T_DATAXFER data transfer 

T_OUTREL outgoing orderly release (waiting for an ord- 
erly release indication) 

TJNREL incoming orderly release (waiting for an ord- 

erly release request) 

If the provider is undergoing a state transition when tjjetstate 
is called, the function will fail. 
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NAME 

tjisten - listen for a connect request 

SYNOPSIS 

#include <tiuser.h> 

int t_listen(fd, call) 
int fd; 

struct t call *call; 
DESCRIPTION 

This function listens for a connect request from a calling tran- 
sport user. Fd identifies the local transport endpoint where 
connect indications arrive, and on return, call contains infor- 
mation describing the connect indication. Call points to a 
t_call structure which contains the following members: 



struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 
int sequence; 



Netbuf is described in intro[3). In call, addr returns the proto- 
col address of the calling transport user, opt returns protocol- 
specific parameters associated with the connect request, 
udata returns any user data sent by the caller on the connect 
request, and sequence is a number that uniquely identifies the 
returned connect indication. The value of sequence enables 
the user to listen for multiple connect indications before 
responding to any of them. 

Since this function returns values for the addr, opt, and udata 
fields of call, the maxlen [see netbuf in intro(3)] field of each 
must be set before issuing the tjisten to indicate the max- 
imum size of the buffer for each. 

By default, tjisten executes in synchronous mode and waits 
for a connect indication to arrive before returning to the user. 
However, if 0_NDELAY is set (via t open or fcntl), tjisten exe- 
cutes asynchronously, reducing to a poll for existing connect 
indications. If none are available, it returns -1 and sets t_errno 
to TNODATA. 

On failure, tjerrno may be set to one of the following: 
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[TBADF] 



The specified file descriptor does not 
refer to a transport endpoint. 



[TBUFOVFLW] 



The number of bytes allocated for an 
incoming argument is not sufficient to 
store the value of that argument. The 
provider's state, as seen by the user, 
changes to TJNCON, and the connect 
indication information to be returned in 
call is discarded. 



[TNODATA] 



0_NDE1_AY was set, but no connect indi- 
cations had been queued. 



[TLOOK] 



An asynchronous event has occurred on 
this transport endpoint and requires 
immediate attention. 



[TNOTSUPPORT] This function is not supported by the 
underlying transport provider. 



CAVEATS 

If a user issues tjisten in synchronous mode on a transport 
endpoint that was not bound for listening (i.e. qlen was zero 
on t_bind), the call will wait forever because no connect indica- 
tions will arrive on that endpoint. 

SEE ALSO 

intro(3), t_accept(3N), t_bind(3N), t_connect(3N), t_open(3N), 

t_rcvconnect(3N). 

Network Programmer's Guide 

DIAGNOSTICS 

t listen returns 0 on success and -1 on failure and t_errno is 
set to indicate the error. 
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A system error has occurred during exe- 
cution of this function. 



T_LOOK(3N) 



NAME 

tjook - look at the current event on a transport end point 

SYNOPSIS 

#include <tiuser.h> 

int tjook(fd) 
int fd; 

DESCRIPTION 

This function returns the current event on the transport end- 
point specified by fd. This function enables a transport pro- 
vider to notify a transport user of an asynchronous event 
when the user is issuing functions in synchronous mode. Cer- 
tain events require immediate notification of the user and are 
indicated by a specific error, TLOOK, on the current or next 
function to be executed. 

This function also enables a transport user to poll a transport 
endpoint periodically for asynchronous events. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to 

a transport endpoint. 

[TSYSERR] A system error has occurred during execution 
of this function. 

SEE ALSO 

t_open(3N). 

Network Programmer's Guide 
DIAGNOSTICS 

Upon success, tjook returns a value that indicates which of 
the allowable events has occurred, or returns zero if no event 
exists. One of the following events is returned: 

TJJSTEN connection indication received 

T CONNECT connect confirmation received 

T DATA normal data received 

T_EXDATA expedited data received 

T_DISCONNECT disconnect received 

T ERROR fatal error indication 
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TJJDERR datagram error indication 

T_ORDREL orderly release indication 

On failure, -1 is returned and tjsrrno is set to indicate the 
error. 
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NAME 

t_open - establish a transport endpoint 

SYNOPSIS 

#include <tiuser.h> 

int t_open(path, of lag, info) 
char *path; 
int of lag; 

struct tjnfo *info; 
DESCRIPTION 

t_open must be called as the first step in the initialization of a 
transport endpoint. This function establishes a transport end- 
point by opening a UNIX* file that identifies a particular tran- 
sport provider (i.e. transport protocol) and returning a file 
descriptor that identifies that endpoint. For example, opening 
the file /dev/iso_cots identifies an OSI connection-oriented 
transport layer protocol as the transport provider. 

Path points to the path name of the file to open, and of lag 
identifies any open flags [as in open (2)]. t_open returns a file 
descriptor that will be used by all subsequent functions to 
identify the particular local transport endpoint. 

This function also returns various default characteristics of the 
underlying transport protocol by setting fields in the tjnfo 
structure. This argument points to a tjnfo which contains the 
following members: 

long addr; /* max size of the transport protocol address */ 
long options; /* max number of bytes of protocol -specific 
options */ 

long tsdu; /* max size of a transport service data unit 
(TSDU) */ 

long etsdu; /* max size of an expedited transport service 

data unit (ETSDU) */ 
long connect; /* max amount of data allowed on connection 

establishment functions */ 



*UNIX is a registered trademark of AT&T in the USA and other 
count ires. Portions of the Unisys System V Operating System 
are derived from the AT&T V.3 UNIX release. 
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long discon; /* max amount of data allowed on t_snddis and 

t_rcvdis functions */ 

long servtype; /* service type supported by the transport 

provider */ 



The values of the fields have the following meanings: 



addr 



options 



tsdu 



etsdu 



A value greater than or equal to zero indicates 
the maximum size of a transport protocol 
address; a value of -1 specifies that there is no 
limit on the address size; and a value of -2 
specifies that the transport provider does not 
provide user access to transport protocol 
addresses. 

A value greater than or equal to zero indicates 
the maximum number of bytes of protocol- 
specific options supported by the provider; a 
value of -1 specifies that there is no limit on the 
option size; and a value of -2 specifies that the 
transport provider does not support user- 
settable options. 

A value greater than zero specifies the max- 
imum size of a transport service data unit 
(TSDU); a value of zero specifies that the tran- 
sport provider does not support the concept of 
TSDU, although it does support the sending of 
a data stream with no logical boundaries 
preserved across a connection; a value of -1 
specifies that there is no limit on the size of a 
TSDU; and a value of -2 specifies that the 
transfer of normal data is not supported by the 
transport provider. 

A value greater than zero specifies the max- 
imum size of an expedited transport service 
data unit (ETSDU); a value of zero specifies 
that the transport provider does not support 
the concept of ETSDU, although it does sup- 
port the sending of an expedited data stream 
with no logical boundaries preserved across a 
connection; a value of -1 specifies that there is 
no limit on the size of an ETSDU; and a value 
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of -2 specifies that the transfer of expedited 
data is not supported by the transport pro- 
vider. 

connect A value greater than or equal to zero specifies 
the maximum amount of data that may be 
associated with connection establishment func- 
tions; a value of -1 specifies that there is no 
limit on the amount of data sent during con- 
nection establishment; and a value of -2 speci- 
fies that the transport provider does not allow 
data to be sent with connection establishment 
functions. 

discon A value greater than or equal to zero specifies 

the maximum amount of data that may be 
associated with the t_snddis and t_rcvdis func- 
tions; a value of -1 specifies that there is no 
limit on the amount of data sent with these 
abortive release functions; and a value of -2 
specifies that the transport provider does not 
allow data to be sent with the abortive release 
functions. 

sen/type This field specifies the service type supported 
by the transport provider, as described below. 

If a transport user is concerned with protocol independence, 
the above sizes may be accessed to determine how large the 
buffers must be to hold each piece of information. Alterna- 
tively, the t_alloc function may be used to allocate these 
buffers. An error will result if a transport user exceeds the 
allowed data size on any function. 

The sen/type field of info may specify one of the following 
values on return: 

T_COTS The transport provider supports a connection- 
mode service but does not support the 
optional orderly release facility. 

T_COTS_ORD The transport provider supports a connection- 
mode service with the optional orderly release 
facility. 
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T_CLTS The transport provider supports a 

connectionless-mode service. For this service 
type, t_open will return -2 for etsdu, connect, 
and discon. 

A single transport endpoint may support only one of the 
above services at one time. 

If info is set to ULL by the transport user, no protocol informa- 
tion is returned by t_open. 

On failure, tjerrno may be set to the following: 

[TSYSERR] A system error has occurred during exe- 

cution of this function. 

SEE ALSO 

open (2). 

Network Programmer's Guide 

DIAGNOSTICS 

t_open returns a valid file descriptor on success and -1 on 
failure and t errno is set to indicate the error. 
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NAME 

t_optmgmt - manage options for a transport endpoint 

SYNOPSIS 

#include <tiuser.h> 

int t_optmgmt(fd, req, ret) 
int fd; 

struct t optmgmt *req; 
struct t_optmgmt *ret; 

DESCRIPTION 

The t_optmgmt function enables a transport user to retrieve, 
verify, or negotiate protocol options with the transport pro- 
vider. Fd identifies a bound transport endpoint. 

The req and ret arguments point to a t_optmgmt structure 
containing the following members: 

struct netbuf opt; 
long flags; 

The opt field identifies protocol options and the flags field is 
used to specify the action to take with those options. 

The options are represented by a netbuf [see intro(3); also for 
len, buf and maxlen] structure in a manner similar to the 
address in t_bind. Req is used to request a specific action of 
the provider and to send options to the provider. Len speci- 
fies the number of bytes in the options, buf points to the 
options buffer, and maxlen has no meaning for the req argu- 
ment. The transport provider may return options and flag 
values to the user through ret. For ret, maxlen specifies the 
maximum size of the options buffer and buf points to the 
buffer where the options are to be placed. On return, len 
specifies the number of bytes of options returned. Maxlen 
has no meaning for the req argument, but must be set in the 
ret argument to specify the maximum number of bytes the 
options buffer can hold. The actual structure and content of 
the options is imposed by the transport provider. 

The flags field of req can specify one of the following actions: 

T NEGOTIATE This action enables the user to negotiate the 
values of the options specified in req with the 
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transport provider. The provider will evaluate 
the requested options and negotiate the 
values, returning the negotiated values 
through ret. 

T_CHECK This action enables the user to verify whether 
the options specified in req are supported by 
the transport provider. On return, the flags 
field of ret will have either T_SUCCESS or 
T_FAILURE set to indicate to the user whether 
the options are supported. These flags are 
only meaningful for the T_CHECK request. 

T_DEFAULT This action enables a user to retrieve the 
default options supported by the transport 
provider into the opt field of ret. In req, the 
len field of opt must be zero and the buf field 
may be NULL. 

If issued as part of the connectionless-mode service, 
t_optmgmt may block due to flow control constraints. The 
function will not complete until the transport provider has pro- 
cessed all previously sent data units. 

On failure, tjerrno may be set to one of the following: 

The specified file descriptor does not 
refer to a transport endpoint. 

The function was issued in the wrong 
sequence. 

The user does not have permission to 
negotiate the specified options. 

The specified protocol options were in 
an incorrect format or contained illegal 
information. 



[TBADF] 
[TOUTSTATE] 
[TACCES] 
[TBADOPT] 

[TBADFLAG] 
[TBUFOVFLW] 



An invalid flag was specified. 

The number of bytes allowed for an 
incoming argument is not sufficient to 
store the value of that argument. The 
information to be returned in ret will be 
discarded. 
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[TSYSERR] A system error has occurred during exe- 

cution of this function. 

SEE ALSO 

intro(3), t_getinfo(3N), t_open(3N). 
Network Programmer's Guide 

DIAGNOSTICS 

t_optmgmt returns 0 on success and -1 on failure and t_ermo 
is set to indicate the error. 
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NAME 

t_rcv - receive data or expedited data sent over a connection 

SYNOPSIS 

int t_rcv(fd, buf, nbytes, flags) 
int fd; 
char *buf; 
unsigned nbytes; 
int *flags; 

DESCRIPTION 

This function receives either normal or expedited data. Fd 
identifies the local transport endpoint through which data will 
arrive, buf points to a receive buffer where user data will be 
placed, and nbytes specifies the size of the receive buffer. 
Flags may be set on return from t_rcv and specifies optional 
flags as described below. 

By default, t_rcv operates in synchronous mode and will wait 
for data to arrive if none is currently available. However, if 
0_NDELAY is set (via t_open or fcntl), t_rcv will execute in 
asynchronous mode and will fail if no data is available. (See 
TNODATA below.) 

On return from the call, if T_MORE is set in flags this indicates 
that there is more data and the current transport service data 
unit (TSDU) or expedited transport service data unit (ETSDU) 
must be received in multiple t_rcv calls. Each t_rcv with the 
T_MORE flag set indicates that another tjcv must follow 
immediately to get more data for the current TSDU. The end 
of the TSDU is identified by the return of a t_rcv call with the 
T_MORE flag not set. If the transport provider does not sup- 
port the concept of a TSDU as indicated in the info argument 
on return from t_open or tjgetinfo, the T_MORE flag is not 
meaningful and should be ignored. 

On return, the data returned is expedited data if 
T_EXPEDITED is set in flags. If the number of bytes of 
expedited data exceeds nbytes, tjcv will set T_EXPEDITED 
and T_MORE on return from the initial call. Subsequent calls 
to retrieve the remaining ETSDU will not have T EXPEDITED 
set on return. The end of the ETSDU is identified by the 
return of a tjcv call with the T MORE flag not set. 
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If expedited data arrives after part of a TSDU has been 
retrieved, receipt of the remainder of the TSDU will be 
suspended until the ETSDU has been processed. Only after 
the full ETSDU has been retrieved (T MORE not set) will the 
remainder of the TSDU be available to the user. 

On failure, t_errno may be set to one of the following: 



[TBADF] 
[TNODATA] 

[TLOOK] 

[TNOTSUPPORT] 
[TSYSERR] 



The specified file descriptor does not 
refer to a transport endpoint. 

0_NDELAY was set, but no data is 
currently available from the transport pro- 
vider. 

An asynchronous event has occurred on 
this transport endpoint and requires 
immediate attention. 

This function is not supported by the 
underlying transport provider. 

A system error has occurred during exe- 
cution of this function. 



SEE ALSO 

t_open(3N), t_snd(3N). 
Network Programmer's Guide 

DIAGNOSTICS 

On successful completion, t_rcv returns the number of bytes 
received, and it returns -1 on failure and t_errno is set to indi- 
cate the error. 
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NAME 

t_rcvconnect - receive the confirmation from a connect 
request 

SYNOPSIS 

#include <tiuser.h> 

int t_rcvconnect(fd, call) 
int fd; 

struct t_call *call; 
DESCRIPTION 

This function enables a calling transport user to determine the 
status of a previously sent connect request and is used in con- 
junction with tconnect to establish a connection in asynchro- 
nous mode. The connection will be established on successful 
completion of this function. 

Fd identifies the local transport endpoint where communica- 
tion will be established, and call contains information associ- 
ated with the newly established connection. Call points to a 
t_call structure which contains the following members: 

struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 
int sequence; 

Netbuf is described in intro(3). In call, addr returns the proto- 
col address associated with the responding transport end- 
point, opt presents any protocol-specific information associ- 
ated with the connection, udata points to optional user data 
that may be returned by the destination transport user during 
connection establishment, and sequence has no meaning for 
this function. 

The maxlen [see netbuf in intro(3)] field of each argument 
must be set before issuing this function to indicate the max- 
imum size of the buffer for each. However, call may be NULL, 
in which case no information is given to the user on return 
from tjcvconnect. By default, tjcvconnect executes in syn- 
chronous mode and waits for the connection to be established 
before returning. On return, the addr, opt, and udata fields 
reflect values associated with the connection. 
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If 0_NDELAY is set (via t_open or fcntl), t_rcvconnect exe- 
cutes in asynchronous mode, and reduces to a poll for exist- 
ing connect confirmations. If none are available, t_rcvconnect 
fails and returns immediately without waiting for the connec- 
tion to be established. (See TNODATA below.) tjcvconnect 
must be re-issued at a later time to complete the connection 
establishment phase and retrieve the information returned in 
call. 

On failure, t_errno may be set to one of the following: 



[TBADF] 



[TBUFOVFLW] 



[TNODATA] 
[TLOOK] 

[TNOTSUPPORT] 
[TSYSERR] 



The specified file descriptor does not 
refer to a transport endpoint. 

The number of bytes allocated for an 
incoming argument is not sufficient to 
store the value of that argument and the 
connect information to be returned in 
call will be discarded. The provider's 
state, as seen by the user, will be 
changed to DATAXFER. 

0_NDELAY was set, but a connect con- 
firmation has not yet arrived. 

An asynchronous event has occurred on 
this transport connection and requires 
immediate attention. 

This function is not supported by the 
underlying transport provider. 

A system error has occurred during exe- 
cution of this function. 



SEE ALSO 

intro(3), t_accept(3N), t_bind(3N), t_connect(3N), t_listen(3N), 
t_open(3N). 

Programmer's Network Guide 

DIAGNOSTICS 

t_rcvconnect returns 0 on success and -1 on failure and 
t errno is set to indicate the error. 
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NAME 

t_rcvdis - retrieve information from disconnect 

SYNOPSIS 

#include <tiuser.h> 

t_rcvdis(fd, discon) 
int fd; 

struct t discon *discon; 
DESCRIPTION 

This function is used to identify the cause of a disconnect, and 
to retrieve any user data sent with the disconnect. Fd identi- 
fies the local transport endpoint where the connection existed, 
and discon points to a t_discon structure containing the fol- 
lowing members: 



struct netbuf udata; 
int reason; 
int sequence; 

Netbuf is described in intro(3). Reason specifies the reason 
for the disconnect through a protocol-dependent reason code, 
udata identifies any user data that was sent with the discon- 
nect, and sequence may identify an outstanding connect indi- 
cation with which the disconnect is associated. Sequence is 
only meaningful when t_rcvdis is issued by a passive transport 
user who has executed one or more tjisten functions and is 
processing the resulting connect indications. If a disconnect 
indication occurs, sequence can be used to identify which of 
the outstanding connect indications is associated with the 
disconnect. 

If a user does not care if there is incoming data and does not 
need to know the value of reason or sequence, discon may 
be NULL and any user data associated with the disconnect will 
be discarded. However, if a user has retrieved more than one 
outstanding connect indication (via tjisten) and discon is 
NULL, the user will be unable to identify with which connect 
indication the disconnect is associated. 

On failure, tjerrno may be set to one of the following: 

[TBADF] The specified file descriptor does not 

refer to a transport endpoint. 
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[TNODIS] 



No disconnect indication currently exists 
on the specified transport endpoint. 



[TBUFOVFLW] 



The number of bytes allocated for 
incoming data is not sufficient to store 
the data. The provider's state, as seen 
by the user, will change to TJDLE, and 
the disconnect indication information to 
be returned in discon will be discarded. 



[TNOTSUPPORT] This function is not supported by the 
underlying transport provider. 



SEE ALSO 

intro(3), t_connect(3N), t_listen(3N), t_open(3N), t_snddis(3N). 
Network Programmer's Guide 

DIAGNOSTICS 

tjcvdis returns 0 on success and -1 on failure and t errno is 
set to indicate the error. 
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A system error has occurred during exe- 
cution of this function. 
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NAME 

trcvrel - acknowledge receipt of an orderly release indication 

SYNOPSIS 

#include <tiuser.h> 

t_rcvrel(fd) 
int fd; 

DESCRIPTION 

This function is used to acknowledge receipt of an orderly 
release indication. Fd identifies the local transport endpoint 
where the connection exists. After receipt of this indication, 
the user may not attempt to receive more data because such 
an attempt will block forever. However, the user may continue 
to send data over the connection if tsndrel has not been 
issued by the user. 

This function is an optional service of the transport provider, 
and is only supported if the transport provider returned ser- 
vice type T_COTS_ORD on t_open or t_getinfo. 

On failure, tjerrno may be set to one of the following: 

[TBADF] The specified file descriptor does not 

refer to a transport endpoint. 

[TNOREL] No orderly release indication currently 

exists on the specified transport end- 
point. 

[TLOOK] An asynchronous event has occurred on 

this transport endpoint and requires 
immediate attention. 

[TNOTSUPPORT] This function is not supported by the 
underlying transport provider. 

[TSYSERR] A system error has occurred during exe- 

cution of this function. 

SEE ALSO 

t_open(3N), t_sndrel(3N). 
Network Programmer's Guide 

DIAGNOSTICS 

tjcvrel returns 0 on success and -1 on failure t errno is set to 
indicate the error. 
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NAME 

t_rcvudata - receive a data unit 

SYNOPSIS 

#include <tiuser.h> 

int t_rcvudata(fd, unitdata, flags) 
int fd; 

struct t unitdata *unitdata; 
int *flags; 

DESCRIPTION 

This function is used in connectionless mode to receive a data 
unit from another transport user. Fd identifies the local tran- 
sport endpoint through which data will be received, unitdata 
holds information associated with the received data unit, and 
flags is set on return to indicate that the complete data unit 
was not received. Unitdata points to a t_unitdata structure 
containing the following members: 



struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 

The maxlen [see netbuf\n intro{3)] field of addr, opt, and udata 
must be set before issuing this function to indicate the max- 
imum size of the buffer for each. 

On return from this call, addr specifies the protocol address of 
the sending user, opt identifies protocol-specific options that 
were associated with this data unit, and udata specifies the 
user data that was received. 

By default, tjcvudata operates in synchronous mode and will 
wait for a data unit to arrive if none is currently available. 
However, if 0_NDELAY is set (via t_open or fcntl), tjcvudata 
will execute in asynchronous mode and will fail if no data units 
are available. 

If the buffer defined in the udata field of unitdata is not large 
enough to hold the current data unit, the buffer will be filled 
and T_MORE will be set in flags on return to indicate that 
another tjcvudata should be issued to retrieve the rest of the 
data unit. Subsequent tjcvudata call(s) will return zero for 
the length of the address and options until the full data unit 
has been received. 
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On failure, t_errno may be set to one of the following: 



[TBADF] 
[TNODATA] 

[TBUFOVFLW] 



[TLOOK] 

[TNOTSUPPORT] 
[TSYSERR] 



The specified file descriptor does not 
refer to a transport endpoint. 

0_NDELAY was set, but no data units 
are currently available from the transport 
provider. 

The number of bytes allocated for the 
incoming protocol address or options is 
not sufficient to store the information. 
The unit data information to be returned 
in unitdata will be discarded. 

An asynchronous event has occurred on 
this transport endpoint and requires 
immediate attention. 

This function is not supported by the 
underlying transport provider. 

A system error has occurred during exe- 
cution of this function. 



SEE ALSO 

intro(3), t_rcvuderr(3N), t_sndudata(3N). 
Network Programmer's Guide 

DIAGNOSTICS 

t_rcvudata returns 0 on successful completion and -1 on 
failure and t errno is set to indicate the error. 
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NAME 

t_rcvuderr - receive a unit data error indication 

SYNOPSIS 

#include <tiuser.h> 

int t rcvuderr(fd, uderr) 
int fd; 

struct t_uderr *uderr; 
DESCRIPTION 

This function is used in connectionless mode to receive infor- 
mation concerning an error on a previously sent data unit, and 
should only be issued following a unit data error indication. It 
informs the transport user that a data unit with a specific des- 
tination address and protocol options produced an error. Fd 
identifies the local transport endpoint through which the error 
report will be received, and uderr points to a tuderr structure 
containing the following members: struct netbuf addr; 
struct netbuf opt; long error; 

Netbuf is described in intro(3). The maxlen [see netbuf in 
intro(3)] field of addr and opt must be set before issuing this 
function to indicate the maximum size of the buffer for each. 

On return from this call, the addr structure specifies the desti- 
nation protocol address of the erroneous data unit, the opt 
structure identifies protocol-specific options that were associ- 
ated with the data unit, and error specifies a protocol- 
dependent error code. 

If the user does not care to identify the data unit that pro- 
duced an error, uderr may be set to NULL and tjcvuderr will 
simply clear the error indication without reporting any informa- 
tion to the user. 

On failure, tjerrno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer 

to a transport endpoint. 

[TNOUDERR] No unit data error indication currently 
exists on the specified transport endpoint. 

[TBUFOVFLW] The number of bytes allocated for the 
incoming protocol address or options is 
not sufficient to store the information. The 
unit data error information to be returned 
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in uderr will be discarded. 

[TNOTSUPPORT] This function is not supported by the 
underlying transport provider. 

[TSYSERR] A system error has occurred during execu- 

tion of this function. 

SEE ALSO 

intro(3), t_rcvudata(3N), t_sndudata(3N). 
Network Programmer's Guide 

DIAGNOSTICS 

tjcvuderr returns 0 on successful completion and -1 on failure 
and t errno is set to indicate the error. 
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NAME 

t_snd - send data or expedited data over a connection 

SYNOPSIS 

#include <tiuser.h> 

int t_snd(fd, buf, n bytes, flags) 
int fd; 
char *buf; 
unsigned nbytes; 
int flags; 

DESCRIPTION 

This function is used to send either normal or expedited data. 
Fd identifies the local transport endpoint over which data 
should be sent, buf points to the user data, nbytes specifies 
the number of bytes of user data to be sent, and flags speci- 
fies any optional flags described below. 

By default, tjsnd operates in synchronous mode and may wait 
if flow control restrictions prevent the data from being 
accepted by the local transport provider at the time the call is 
made. However, if 0_NDELAY is set (via t_open or fcntl), 
tjsnd will execute in asynchronous mode, and will fail immedi- 
ately if there are flow control restrictions. 

On successful completion, tjsnd returns the number of bytes 
accepted by the transport provider. Normally this will equal 
the number of bytes specified in nbytes. However, if 
0_NDELAY is set, it is possible that only part of the data will 
be accepted by the transport provider. In this case, tsnd will 
set T_MORE for the data that was sent (see below) and will 
return a value less than nbytes. If nbytes is zero, no data will 
be passed to the provider and tjsnd will return zero. 

If T_EXPEDITED is set in flags, the data will be sent as 
expedited data, and will be subject to the interpretations of 
the transport provider. 

If T_MORE is set in flags, or set as described above, an indi- 
cation is sent to the transport provider that the transport ser- 
vice data unit (TSDU) (or expedited transport service data unit 
- ETSDU) is being sent through multiple t snd calls. Each 
tjsnd with the T_MORE flag set indicates that another tjsnd 
will follow with more data for the current TSDU. The end of 
the TSDU (or ETSDU) is identified by a tjsnd call with the 
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T_MORE flag not set. Use of T_MORE enables a user to 
break up large logical data units without losing the boundaries 
of those units at the other end of the connection. The flag 
implies nothing about how the data is packaged for transfer 
below the transport interface. If the transport provider does 
not support the concept of a TSDU as indicated in the info 
argument on return from t_open or tjgetinfo, the T_MORE 
flag is not meaningful and should be ignored. 

The size of each TSDU or ETSDU must not exceed the limits 
of the transport provider as returned by t_open or tjgetinfo. 
Failure to comply will result in protocol error EPROTO. (See 
TSYSERR below.) 

If tsnd is issued from the T IDLE state, the provider may 
silently discard the data. If t snd is issued from any state 
other than T DATAXFER or TJDLE, the provider will generate 
an EPROTO error. 

On failure, tjarrno may be set to one of the following: 

[TBADF] The specified file descriptor does not 

refer to a transport endpoint. 

[TFLOW] O NDELAY was set, but the flow control 

mechanism prevented the transport pro- 
vider from accepting data at this time. 

[TNOTSUPPORT] This function is not supported by the 
underlying transport provider. 

[TSYSERR] A system error has occurred during exe- 

cution of this function. 

SEE ALSO 

t_open(3N), t_rcv(3N). 
Network Programmer's Guide 

DIAGNOSTICS 

On successful completion, t snd returns the number of bytes 
accepted by the transport provider, and it returns -1 on failure 
and t errno is set to indicate the error. 
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NAME 

t snddis - send user-initiated disconnect request 

SYNOPSIS 

#include <tiuser.h> 

int t_snddis(fd, call) 
int fd; 

struct t_call *call; 
DESCRIPTION 

This function is used to initiate an abortive release on an 
already established connection or to reject a connect request. 
Fd identifies the local transport endpoint of the connection, 
and call specifies information associated with the abortive 
release. Call points to a t_call structure which contains the 
following members: 

struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 
int sequence; 

Netbuf is described in intro{3). The values in call have dif- 
ferent semantics, depending on the context of the call to 
tjsnddis. When rejecting a connect request, call must be 
non-NULL and contain a valid value of sequence to uniquely 
identify the rejected connect indication to the transport pro- 
vider. The addr and opt fields of call are ignored. In all other 
cases, call need only be used when data is being sent with the 
disconnect request. The addr, opt, and sequence fields of the 
t_call structure are ignored. If the user does not wish to send 
data to the remote user, the value of call may be NULL. 

Udata specifies the user data to be sent to the remote user. 
The amount of user data must not exceed the limits supported 
by the transport provider as returned by t_open or t getinfo. 
If the len field of udata is zero, no data will be sent to the 
remote user. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not 

refer to a transport endpoint. 
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[TOUTSTATE] 



[TBADDATA] 



[TBADSEQ] 



[TLOOK] 

[TNOTSUPPORT] 
[TSYSERR] 



The function was issued in the wrong 
sequence. The transport provider's out- 
going queue may be flushed, so data 
may be lost. 

The amount of user data specified was 
not within the bounds allowed by the 
transport provider. The transport 
provider's outgoing queue will be flushed, 
so data may be lost. 

An invalid sequence number was speci- 
fied, or a NULL call structure was speci- 
fied when rejecting a connect request. 
The transport provider's outgoing queue 
will be flushed, so data may be lost. 

An asynchronous event has occurred on 
this transport endpoint and requires 
immediate attention. 

This function is not supported by the 
underlying transport provider. 

A system error has occurred during exe- 
cution of this function. 



SEE ALSO 

intro(3), t_connect(3N), t_getinfo(3N), t_listen(3N), t_open(3N). 
Network Programmer's Guide 

DIAGNOSTICS 

tsnddis returns 0 on success and -1 on failure and t_errno is 
set to indicate the error. 
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NAME 

t sndrel - initiate an orderly release 

SYNOPSIS 

#include <tiuser.h> 

int tsndrel(fd) 
int fd; 

DESCRIPTION 

This function is used to initiate an orderly release of a tran- 
sport connection and indicates to the transport provider that 
the transport user has no more data to send. Fd identifies the 
local transport endpoint where the connection exists. After 
issuing tjsndrel, the user may not send any more data over 
the connection. However, a user may continue to receive data 
if an orderly release indication has been received. 

This function is an optional service of the transport provider, 
and is only supported if the transport provider returned ser- 
vice type T_COTS_ORD on t_open or t_getinfo. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not 

refer to a transport endpoint. 

[TFLOW] 0_NDELAY was set, but the flow control 

mechanism prevented the transport pro- 
vider from accepting the function at this 
time. 

[TNOTSUPPORT] This function is not supported by the 
underlying transport provider. 

[TSYSERR] A system error has occurred during exe- 

cution of this function. 

SEE ALSO 

t_open(3N), t_rcvrel(3N). 
Network Programmer's Guide 

DIAGNOSTICS 

tjsndrel returns 0 on success and -1 on failure and tjerrno is 
set to indicate the error. 
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NAME 

t_sndudata - send a data unit 

SYNOPSIS 

#include <tiuser.h> 

int t_sndudata(fd, unitdata) 
int fd; 

struct t unitdata *unitdata; 
DESCRIPTION 

This function is used in connectionless mode to send a data 
unit to another transport user. Fd identifies the local transport 
endpoint through which data will be sent, and unitdata points 
to a tjinitdata structure containing the following members: 



struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 



Netbuf is described in intro{3). In unitdata, addr specifies the 
protocol address of the destination user, opt identifies 
protocol-specific options that the user wants associated with 
this request, and udata specifies the user data to be sent. 
The user may choose not to specify what protocol options are 
associated with the transfer by setting the ten field of opt to 
zero. In this case, the provider may use default options. 

If the ten field of udata is zero, no data unit will be passed to 
the transport provider; tsndudata will not send zero-length 
data units. 

By default, t sndudata operates in synchronous mode and 
may wait if flow control restrictions prevent the data from 
being accepted by the local transport provider at the time the 
call is made. However, if O NDELAY is set (via t_open or 
fcntl), tjsndudata will execute in asynchronous mode and will 
fail under such conditions. 

If t sndudata is issued from an invalid state, or if the amount 
of data specified in udata exceeds the TSDU size as returned 
by t open or tjgetinfo, the provider will generate an EPROTO 
protocol error. (See TSYSERR below.) 
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On failure, t_errno may be set to one of the following: 

The specified file descriptor does not refer 
to a transport endpoint. 

0_NDELAY was set, but the flow control 
mechanism prevented the transport pro- 
vider from accepting data at this time. 

This function is not supported by the 
underlying transport provider. 

A system error has occurred during execu- 
tion of this function. 



[TBADF] 
[TFLOW] 

[TNOTSUPPORT] 
[TSYSERR] 



SEE ALSO 

intro(3), t_rcvudata(3N), t_rcvuderr(3N). 
Network Programmer's Guide 

DIAGNOSTICS 

tjsndudata returns 0 on successful completion and -1 
failure t errno is set to indicate the error. 
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NAME 

t_sync - synchronize transport library 

SYNOPSIS 

#include <tiuser.h> 

int t_sync(fd) 
int fd; 

DESCRIPTION 

For the transport endpoint specified by fd t tjsync synchron- 
izes the data structures managed by the transport library with 
information from the underlying transport provider. In doing 
so, it can convert a raw file descriptor [obtained via open (2), 
dup{2), or as a result of a fork{2) and exec{2)] to an initialized 
transport endpoint, assuming that file descriptor referenced a 
transport provider. This function also allows two cooperating 
processes to synchronize their interaction with a transport pro- 
vider. 

For example, if a process forks a new process and issues an 
exec, the new process must issue a tjsync to build the private 
library data structure associated with a transport endpoint and 
to synchronize the data structure with the relevant provider 
information. 

It is important to remember that the transport provider treats 
all users of a transport endpoint as a single user. If multiple 
processes are using the same endpoint, they should coordi- 
nate their activities so as not to violate the state of the pro- 
vider, tsync returns the current state of the provider to the 
user, thereby enabling the user to verify the state before tak- 
ing further action. This coordination is only valid among 
cooperating processes; it is possible that a process or an 
incoming event could change the provider's state after a 
tjsync is issued. 

If the provider is undergoing a state transition when tjsync is 
called, the function will fail. 

On failure, tjerrno may be set to one of the following: 

[TBADF] The specified file descriptor is a valid 

open file descriptor but does not refer to 
a transport endpoint. 
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[TSTATECHNG] The transport provider is undergoing a 
state change. 

[TSYSERR] A system error has occurred during exe- 

cution of this function. 

SEE ALSO 

dup(2), exec(2), fork (2), open(2). 
Network Programmer's Guide 

DIAGNOSTICS 

tjsync returns the state of the transport provider on success- 
ful completion and -1 on failure and t_errno is set to indicate 
the error. The state returned may be one of the following: 



T 


UNBND 


unbound 


T 


IDLE 


idle 


T 


OUTCON 


outgoing connection pending 


T 


INCON 


incoming connection pending 


T 


DATAXFER 


data transfer 


T 


OUTREL 


outgoing orderly release (waiting for an 
orderly release indication) 


T 


INREL 


incoming orderly release (waiting for an 
orderly release request) 
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NAME 

tjjnbind - disable a transport endpoint 

SYNOPSIS 

#include <tiuser.h> 

int t unbind(fd) 
int fd; 

DESCRIPTION 

The tjjnbind function disables the transport endpoint speci- 
fied by fd which was previously bound by t_bind (3N). On 
completion of this call, no further data or events destined for 
this transport endpoint will be accepted by the transport pro- 
vider. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to 

a transport endpoint. 

[TOUTSTATE] The function was issued in the wrong 
sequence. 

[TLOOK] An asynchronous event has occurred on this 
transport endpoint. 

[TSYSERR] A system error has occurred during execution 
of this function. 

SEE ALSO 

t_bind(3N). 

Network Programmer's Guide 

DIAGNOSTICS 

tjjnbind returns 0 on success and -1 on failure and t_errno is 
set to indicate the error. 
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NAME 

assert - verify program assertion 

SYNOPSIS 

#include < assert. h> 

assert (expression) 
int expression; 

DESCRIPTION 

This macro is useful for putting diagnostics into programs. 
When it is executed, if expression is false (zero), assert prints 

"Assertion failed: expression, file xyz, line nnn" 

on the standard error output and aborts. In the error mes- 
sage, xyz is the name of the source file and nnn the source 
line number of the assert statement. 

Compiling with the preprocessor option -DNDEBUG [see 
C PP COL or with the preprocessor control statement "#define 
NDEBUG" ahead of the "#include <assert.h>" statement, 
will stop assertions from being compiled into the program. 

SEE ALSO 

cpp(1), abort(3C). 

Network Programmer's Guide 

CAVEAT 

Since assert is implemented as a macro, the expression may 
not contain any string literals. 
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NAME 

crypt - password and file encryption functions 

SYNOPSIS 

cc [flag ...] file ... -Icrypt 

char *crypt (key, salt) 
char *key, *salt; 

void setkey (key) 
char *key; 

void encrypt (block, flag) 
char *block; 
int flag; 

char *des_crypt (key, salt) 
char *key, *salt; 

void des setkey (key) 
char *key; 

void des encrypt (block, flag) 
char *block; 
int flag; 

int run setkey (p, key) 
int p[2]; 
char *key; 

int run crypt (offset, buffer, count, p) 
long offset; 
char *buffer; 
unsigned int count; 
int p[2]; 

int crypt close(p) 
int p[2]; ' 

DESCRIPTION 

des_crypt is the password encryption function. It is based on 
a one way hashing encryption algorithm with variations 
intended (among other things) to frustrate use of hardware 
implementations of a key search. 

Key is a user's typed password. Salt is a two-character string 
chosen from the set [a-zA-ZO-9./]; this string is used to per- 
turb the hashing algorithm in one of 4096 different ways, after 
which the password is used as the key to encrypt repeatedly a 
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constant string. The returned value points to the encrypted 
password. The first two characters are the salt itself. 

The desjsetkey and desjencrypt entries provide (rather primi- 
tive) access to the actual hashing algorithm. The argument of 
desjsetkey is a character array of length 64 containing only 
the characters with numerical value 0 and 1. If this string is 
divided into groups of 8, the low-order bit in each group is 
ignored; this gives a 56-bit key which is set into the machine. 
This is the key that will be used with the hashing algorithm to 
encrypt the string block with the function des_encrypt. 

The argument to the desjencrypt entry is a character array of 
length 64 containing only the characters with numerical value 
0 and 1. The argument array is modified in place to a similar 
array representing the bits of the argument after having been 
subjected to the hashing algorithm using the key set by 
des_setkey. If edflag is zero, the argument is encrypted; if 
non-zero, it is decrypted. 

Note that decryption is not provided in the international ver- 
sion of crypt(3X). The international version is part of the C 
Programming Language Utilities, and the domestic version is 
part of the Security Administration Utilities. If decryption is 
attempted with the international version of des_encrypt, an 
error message is printed. 

Crypt, setkey, and encrypt are front-end routines that invoke 
des_crypt, des_setkey, and des_encrypt respectively. 

The routines run_setkey and run_crypt are designed for use by 
applications that need cryptographic capabilities [such as 
ed(1) and w(1)] that must be compatible with the crypt{\) 
user-level utility. Run_setkey establishes a two-way pipe con- 
nection with c/ypr(1), using key as the password argument. 
Run_crypt takes a block of characters and transforms the 
cleartext or ciphertext into their ciphertext or cleartext using 
crypt{l). Offset is the relative byte position from the beginning 
of the file that the block of text provided in block is coming 
from. Count is the number of characters in block, and con- 
nection is an array containing indices to a table of input and 
output file streams. When encryption is finished, cryptclose is 
used to terminate the connection with crypt{X). 
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Runjsetkey returns -1 if a connection with crypt (1) cannot be 
established. This will occur on international versions of UNIX 
where c/ypf(1) is not available. If a null key is passed to 
runjsetkey, 0 is returned. Otherwise, 1 is returned. Run_crypt 
returns -1 if it cannot write output or read input from the pipe 
attached to crypt. Otherwise it returns 0. 

DIAGNOSTICS 

In the international version of crypt(3X), a flag argument of 1 
to desjencrypt is not accepted, and an error message is 
printed. 

SEE ALSO 

getpass(3C), passwd(4). 

crypt(1), login (1), passwd(1) in the User's Reference Manual. 
CAVEAT 

The return value in crypt points to static data that are overwrit- 
ten by each call. 
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NAME 

curses - terminal screen handling and optimization package 
SYNOPSIS 

The curses manual page is organized as follows: 

In SYNOPSIS 

- compiling information 

- summary of parameters used by curses routines 

- alphabetical list of curses routines, showing their 
parameters 

In DESCRIPTION: 

- An overview of how curses routines should be used 

In ROUTINES, descriptions of each curses routines, are 
grouped under the appropriate topics: 

- Overall Screen Manipulation 

- Window and Pad Manipulation 

- Output 

- Input 

- Output Options Setting 

- Input Options Setting 

- Environment Queries 

- Soft Labels 

- Low-level Curses Access 

- Terminfo-Level Manipulations 

- Termcap Emulation 

- Miscellaneous 

- Use of cursor 

Then come sections on: 

- ATTRIBUTES 

- FUNCTION CALLS 

- LINE GRAPHICS 



cc [flag . . .] file . . . -Icurses [library . . .] 
#include < curses. h> 

(automatically includes 
<stdio.h>, <termio.h>, 
and <unctrl.h> ). 
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The parameters in the following list are not global vari- 
ables, but rather this is a summary of the parameters 
used by the curses library routines. All routines return the 
int values ERR or OK unless otherwise noted. Routines 
that return pointers always return NULL on error. (ERR, 
OK, and NULL are all defined in < curses. h>.) Routines 
that return integers are not listed in the parameter list 
below. 

bool bf 

char **area,*boolnames[], *boolcodes[], *boolfnames[], 
*bp 

char *cap, *capname, codename[2], erasechar, *filename, 
*fmt 

char *keyname, killchar, *label, *longname 
char *name, *numnames[], *numcodes[], *numfnames[] 
char *slk_label, *str, *strnames[], *strcodes[], *strfnames[] 
char *term, *tgetstr, *tigetstr, *tgoto, *tparm, *type 

chtype attrs, ch, horch, vertch 

FILE *infd, *outfd 

int begin_x, begin_y, begline, bot, c, col, count 

int dmaxcol, dmaxrow, dmincol, dminrow, *errret, fildes 

int (*init( )), labfmt, labnum, line 

int ms, ncols, new, newcol, newrow, nlines, numlines 

int oldcol, oldrow, overlay 

int p1, p2, p9, pmincol, pminrow, (*putc( )), row 

int smaxcol, smaxrow, smincol, sminrow, start 

int tenths, top, visibility, x, y 

SCREEN *new, *newterm, *set_term 

TERMINAL *cur_term, *nterm, *oterm 

vajist varglist 

WINDOW *curscr, *dstwin, *initscr, *newpad, *newwin, 
*orig 

WINDOW *pad, *srcwin, *stdscr, *subpad, *subwin, *win 

addch(ch) 
addstr(str) 
attroff(attrs) 
attron (attrs) 
attrset(attrs) 
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baud rate () 
beep() 

box(win, vertch, horch) 

cbreakQ 

clear () 

clear ok (win, bf) 

clrtobotQ 

clrtoeolQ 

copywin(srcwin, dstwin, sminrow, smincol, dminrow, 

dmincol, dmaxrow, dmaxcol, overlay)" 
curs_set(visibility) 
def_prog_mode ( ) 
def_shell_mode() 
delcurterm (oterm) 
delay output(ms) 
delchQ 
deleteln() 
del win (win) 
doupdate() 
draino(ms) 
echo() 

echochar(ch) 

endwin() 

erase () 

erasechar() 

filter() 

flash() 

flushinp() 

garbagedlines(win, begline, numlines) 

getbegyx(win, y, x) 

getch() 

getmaxyx(win, y, x) 

getstr(str) 

getsyx(y, x) 

getyx(win, y, x) 

halfdelay(tenths) 

has_ic() 

has_il() 

idlok(win, bf) 

inch() 

initscr() 

insch(ch) 
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insertln() 
intrf lush (win, bf) 
isendwinQ 
keyname (c) 
keypad (win, bf) 
killchar() 
leaveok(win, bf) 
longname() 
meta(win, bf) 
move(y, x) 
mvaddch(y, x, ch) 
mvaddstr(y, x, str) 

mvcur(oldrow, oldcol, newrow, newcol) 
mvdelch(y, x) 
mvgetch(y, x) 
mvgetstr(y, x, str) 
mvinch(y, x) 
mvinsch(y, x, ch) 
mvprintw(y, x, fmt [, arg...]) 
mvscanw(y, x, fmt [, arg...]) 
mvwaddch(win, y, x, ch) 
mvwaddstr(win, y, x, str) 
mvwdelch(win, y, x) 
mvwgetchjwin, y, x) 
mvwgetstr(win, y, x, str) 
mvwin(win, y, x) 
mvwinch(win, y, x) 
mvwinsch(win, y, x, ch) 
mvwprintw(win, y, x, fmt [, arg . . .]) 
mvwscanw(win, y, x, fmt [, arg . . .]) 
napms(ms) 
newpad(nlines, ncols) 
newterm(type, outfd, infd) 
newwin(nlines, ncols, begin y, begin x) 
nl() 

nocbreak() 
nodelay(win, bf) 
noecho() 
nonlQ 
noraw() 

notimeout(win, bf) 
overlay(srcwin, dstwin) 
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overwrite (srcwin, dstwin) 
pechochar(pad, ch) 

pnoutrefresh(pad, pminrow, pmincol, sminrow, smincol, 

smaxrow, smaxcol)" 
prefresh(pad, pminrow, pmincol, sminrow, smincol, 

smaxrow, smaxcol)" 
printw(fmt [, arg...]) 
putp(str) 
raw() 
refresh () 

reset_prog_mode ( ) 
reset_shell_mode ( ) 
resetty() 

restartterm(term, fildes, errret) 
ripoff line (line, init) 
savetty() 

scanw(fmt [, arg...]) 
scrdump (filename) 
scrjnit(filename) 
scr_restore (filename) 
scroll (win) 
scrollok(win, bf) 
set_curterm (nterm) 
set_term(new) 
setscrreg(top, bot) 
setsyx(y, x) 

setupterm(term, fildes, errret) 

slk_clear() 

slk_init(fmt) 

slkjabel(labnum) 

slknoutrefreshQ 

slk_refresh() 

slk_restore() 

slk_set(labnum, label, fmt) 

slk_touch() 

standend() 

standout() 

subpad(orig, nlines, ncols, begin y, begin_x) 
subwin(orig, nlines, ncols, begin_y, begin_x) 
tgetent(bp, name) 
tgetf lag (codename) 
tgetnum (codename) 
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tgetstr(codename, area) 
tgoto(cap, col, row) 
tigetf lag (capname) 
tigetnum (capname) 
tigetstr(capname) 
touchline(win, start, count) 
touchwin(win) 

tparm(str, p1, p2 p9) 

tputs(str, count, putc) 

traceoff() 

fraceonQ 

typeahead(fildes) 

unctrl(c) 

ungetch(c) 

vidattr(attrs) 

vidputs(attrs, putc) 

vwprintw(win, fmt, varglist) 

vwscanwjwin, fmt, varglist) 

waddch(win, ch) 

waddstr(win, str) 

wattroff(win, attrs) 

wattron(win, attrs) 

wattrset(win, attrs) 

wclear(win) 

wclrtobot(win) 

wclrtoeol(win) 

wdelch(win) 

wdeleteln(win) 

wechochar(win, ch) 

werase(win) 

wgetch(win) 

wgetstr(win, str) 

winch (win) 

winsch(win, ch) 

winsertln(win) 

wmove(win, y, x) 

wnoutref resh (win) 

wprintw(win, fmt [, arg...]) 

wref resh (win) 

wscanw(win, fmt [, arg...]) 
wsetscrreg(win, top, bot) 
wstandend(win) 
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wstandout(win) 
DESCRIPTION 

The curses routines give the user a terminal-independent 
method of updating screens with reasonable optimization. 

In order to initialize the routines, the routine initscrQ or 
newterm() must be called before any of the other routines 
that deal with windows and screens are used. (Three excep- 
tions are noted where they apply.) The routine endwin() must 
be called before exiting. To get character-at-a-time input 
without echoing, (most interactive, screen oriented programs 
want this) after calling initscrQ you should call "cbreak(); 
noecho();" Most programs would additionally call "nonl(); 
intrflush (stdscr, FALSE); keypad(stdscr, TRUE);". 

Before a curses program is run, a terminal's tab stops should 
be set and its initialization strings, if defined, must be output. 
This can be done by executing the tput init command after 
the shell environment variable TERM has been exported. For 
further details, see profile{4), tput{1), and the "Tabs and Initiali- 
zation" subsection of terminfo{4). 

The curses library contains routines that manipulate data 
structures called windows that can be thought of as two- 
dimensional arrays of characters representing all or part of a 
terminal screen. A default window called stdscr is supplied, 
which is the size of the terminal screen. Others may be 
created with newwin(). Windows are referred to by variables 
declared as WINDOW *; the type WINDOW is defined in 
<curses.h> to be a C structure. These data structures are 
manipulated with routines described below, among which the 
most basic are move() and addchQ. (More general versions 
of these routines are included with names beginning with w, 
allowing you to specify a window. The routines not beginning 
with w usually affect stdscr.) Then refresh () is called, telling 
the routines to make the user's terminal screen look like 
stdscr. The characters in a window are actually of type 
chtype, so that other information about the character may 
also be stored with each character. 

Special windows called pads may also be manipulated. These 
are windows which are not constrained to the size of the 
screen and whose contents need not be displayed completely. 
See the description of newpad() under "Window and Pad 
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Manipulation" for more information. 

In addition to drawing characters on the screen, video attri- 
butes may be included which cause the characters to show up 
in modes such as underlined or in reverse video on terminals 
that support such display enhancements. Line drawing char- 
acters may be specified to be output. On input, curses is also 
able to translate arrow and function keys that transmit escape 
sequences into single values. The video attributes, line draw- 
ing characters, and input values use names, defined in 
<curses.h>, such as A REVERSE, ACS HLINE, and 
KEYLEFT. 

curses also defines the WINDOW * variable, cursor, which is 
used only for certain low-level operations like clearing and 
redrawing a garbaged screen, cursor can be used in only a 
few routines. If the window argument to clearokQ is curscr, 
the next call to wrefreshQ with any window will cause the 
screen to be cleared and repainted from scratch. If the win- 
dow argument to wrefresh() is curscr, the screen in immedi- 
ately cleared and repainted from scratch. This is how most 
programs would implement a "repaint-screen" function. More 
information on using curscr is provided where its use is 
appropriate. 

The environment variables LINES and COLUMNS may be set 
to override terminfo's idea of how large a screen is. These 
may be used where the size of a screen is changeable. 

If the environment variable TERMINFO is defined, any pro- 
gram using curses will check for a local terminal definition 
before checking in the standard place. For example, if the 
environment variable TERM is set to att4425, then the com- 
piled terminal definition is found in /usr/lib/terminfo/a/att4425. 
(The a is copied from the first letter of att4425 to avoid crea- 
tion of huge directories.) However, if TERMINFO is set to 
$HOME/myterms, curses will first check 
$HOME/myterms/a/att4425, and, if that fails, will then check 
/usr/lib/terminfo/a/att4425. This is useful for developing 
experimental definitions or when write permission on 
/usr/lib/terminfo is not available. 

The integer variables LINES and COLS are defined in 
<curses.h>, and will be filled in by initscr() with the size of 
the screen. (For more information, see the subsection 
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"Terminfo-Level Manipulations".) The constants TRUE and 
FALSE have the values 1 and 0, respectively. The constants 
ERR and OK are returned by routines to indicate whether the 
routine successfully completed. These constants are also 
defined in <curses.h>. 

ROUTINES 

Many of the following routines have two or more versions. 
The routines prefixed with w require a window argument. The 
routines prefixed with p require a pad argument. Those 
without a prefix generally use stdscr. 

The routines prefixed with mv require y and x coordinates to 
move to before performing the appropriate action. The mv() 
routines imply a call to move() before the call to the other 
routine. The window argument is always specified before the 
coordinates, y always refers to the row (of the window), and x 
always refers to the column. The upper left corner is always 
(0,0), not (1,1). The routines prefixed with mvw take both a 
window argument and y and x coordinates. 

In each case, win is the window affected and pad is the pad 
affected, (win and pad are always of type WINDOW *.) 
Option-setting routines require a boolean flag bf with the value 
TRUE or FALSE, (bf is always of type bool.) The types WIN- 
DOW, bool, and chtype are defined in <curses.h>. See the 
SYNOPSIS for a summary of what types all variables are. 

All routines return either the integer ERR or the integer OK, 
unless otherwise noted. Routines that return pointers always 
return NULL on error. 

Overall Screen Manipulation 

WINDOW *initscr() The first routine called should almost 
always be initscrQ. (The exceptions are 
slk_init(), filter(), and ripofflineQ ) This 
will determine the terminal type and ini- 
tialize all curses data structures. 
initscrQ also arranges that the first call 
to refresh () will clear the screen. If 
errors occur, initscrQ will write an 
appropriate error message to standard 
error and exit; otherwise, a pointer to 
stdscr is returned. If the program wants 
an indication of error conditions, 
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newterm() should be used instead of 
initscrQ initscr() should only be called 
once per application. 

endwin() A program should always call endwinQ 

before exiting or escaping from curses 
mode temporarily, to do a shell escape 
or system (3S) call, for example. This 
routine will restore tty{7) modes, move 
the cursor to the lower left corner of the 
screen and reset the terminal into the 
proper non-visual mode. To resume 
after a temporary escape, call 
wrefreshQ or doupdate(). 

isendwinQ Returns TRUE if endwinQ has been 

called without any subsequent calls to 
wrefreshQ. 

SCREEN *newterm(type, outfd, infd) 

A program that outputs to more than 
one terminal must use newtermQ for 
each terminal instead of initscrQ. A 
program that wants an indication of 
error conditions, so that it may continue 
to run in a line-oriented mode if the ter- 
minal cannot support a screen-oriented 
program, must also use this routine. 
newtermQ should be called once for 
each terminal. It returns a variable of 
type SCREEN* that should be saved as 
a reference to that terminal. The argu- 
ments are the type of the terminal to be 
used in place of the environment vari- 
able TERM; outfd, a stdio{3§) file 
pointer for output to the terminal; and 
infd, another file pointer for input from 
the terminal. When it is done running, 
the program must also call endwinQ for 
each terminal being used. If newtermQ 
is called more than once for the same 
terminal, the first terminal referred to 
must be the last one for which endwinQ 
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is called. 

SCREEN *set_term(new) 

This routine is used to switch between 
different terminals. The screen refer- 
ence new becomes the new current ter- 
minal. A pointer to the screen of the 
previous terminal is returned by the rou- 
tine. This is the only routine which mani- 
pulates SCREEN pointers; all other rou- 
tines affect only the current terminal. 

Window and Pad Manipulation 
refresh () 

wrefresh (win) These routines (or prefresh(), 
pnoutrefreshQ, wnoutrefreshQ, or 
doupdateQ) must be called to write out- 
put to the terminal, as most other rou- 
tines merely manipulate data structures, 
wrefresh () copies the named window to 
the physical terminal screen, taking into 
account what is already there in order to 
minimize the amount of information 
that's sent to the terminal (called optimi- 
zation), refresh () does the same thing, 
except it uses stdscr as a default win- 
dow. Unless leaveokQ has been 
enabled, the physical cursor of the ter- 
minal is left at the location of the 
window's cursor. The number of charac- 
ters output to the terminal is returned. 

Note that refresh () is a macro. 

wnoutref resh (win) 

doupdateQ These two routines allow multiple 

updates to the physical terminal screen 
with more efficiency than wrefresh () 
alone. How this is accomplished is 
described in the next paragraph. 

curses keeps two data structures 
representing the terminal screen: a phy- 
sical terminal screen, describing what is 
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actually on the screen, and a virtual ter- 
minal screen, describing what the pro- 
grammer wants to have on the screen. 
wrefreshQ works by first calling 
wnoutrefresh(), which copys the named 
window to the virtual screen, and then 
by calling doupdate(), which compares 
the virtual screen to the physical screen 
and does the actual update. If the pro- 
grammer wishes to output several win- 
dows at once, a series of calls to 
wrefreshQ will result in alternating calls 
to wnoutrefreshQ and doupdateQ, 
causing several bursts of output to the 
screen. By first calling wnoutrefreshQ 
for each window, it is then possible to 
call doupdateQ once, resulting in only 
one burst of output, with probably fewer 
total characters transmitted and certainly 
less processor time used. 

WINDOW *newwin(nlines, ncols, beginy, begin_x) 

Create and return a pointer to a new 
window with the given number of lines 
(or rows), nlines, and columns, ncols. 
The upper left corner of the window is at 
line begin_y, column beginx. If either 
nlines or ncols is 0, they will be set to 
the value of lines-6eg/n_y and 
co\s-begin_x. A new full-screen window 
is created by calling newwin(0, 0,0,0). 

mvwin(win, y, x) Move the window so that the upper left 
corner will be at position (y, x). If the 
move would cause the window to be off 
the screen, it is an error and the window 
is not moved. 

WINDOW *subwin(orig, nlines, ncols, begin y, begin x) 

Create and return a pointer to a new 
window with the given number of lines 
(or rows), nlines, and columns, ncols. 
The window is at position (begin_y, 
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begin_x) on the screen. (This position is 
relative to the screen, and not to the 
window orig.) The window is made in 
the middle of the window orig, so that 
changes made to one window will affect 
both windows. When using this routine, 
often it will be necessary to call 
touchwinQ or touchline() on orig 
before calling wrefreshQ. 

delwin(win) Delete the named window, freeing up all 

memory associated with it. In the case 
of overlapping windows, subwindows 
should be deleted before the main win- 
dow. 

WINDOW *newpad(nlines, ncols) 

Create and return a pointer to a new 
pad data structure with the given 
number of lines (or rows), nlines, and 
columns, ncols. A pad is a window that 
is not restricted by the screen size and 
is not necessarily associated with a par- 
ticular part of the screen. Pads can be 
used when a large window is needed, 
and only a part of the window will be on 
the screen at one time. Automatic 
refreshes of pads (e.g. from scrolling or 
echoing of input) do not occur. It is not 
legal to call wrefresh() with a pad as an 
argument; the routines prefreshQ or 
pnoutrefreshQ should be called instead. 
Note that these routines require addi- 
tional parameters to specify the part of 
the pad to be displayed and the location 
on the screen to be used for display. 

WINDOW *subpad(orig, nlines, ncols, begin_y, begin_x) 

Create and return a pointer to a subwin- 
dow within a pad with the given number 
of lines (or rows), nlines, and columns, 
ncols. Unlike subwinQ, which uses 
screen coordinates, the window is at 
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position (begin _y, begin _x) on the pad. 
The window is made in the middle of the 
window orig, so that changes made to 
one window will affect both windows. 
When using this routine, often it will be 
necessary to call touchwin() or touch- 
line() on orig before calling prefresh(). 

prefresh(pad, pminrow, pmincol, sminrow, smincol, 
smaxrow, smaxcol) 

pnoutrefresh(pad, pminrow, pmincol, sminrow, smincol, 
smaxrow, smaxcol) 

These routines are analogous to 
wrefreshQ and wnoutrefresh() except 
that pads, instead of windows, are 
involved. The additional parameters are 
needed to indicate what part of the pad 
and screen are involved, pminrow and 
pmincol specify the upper left corner, in 
the pad, of the rectangle to be 
displayed, sminrow, smincol, smaxrow, 
and smaxcol specify the edges, on the 
screen, of the rectangle to be displayed 
in. The lower right corner in the pad of 
the rectangle to be displayed is calcu- 
lated from the screen coordinates, since 
the rectangles must be the same size. 
Both rectangles must be entirely con- 
tained within their respective structures. 
Negative values of pminrow, pmincol, 
sminrow, or smincol are treated as if 
they were zero. 

Output 

These routines are used to "draw" text on windows. 

addch(ch) 

waddch(win, ch) 

mvaddch(y, x, ch) 

mvwaddch(win, y, x, ch) 

The character ch is put into the window 
at the current cursor position of the win- 
dow and the position of the window 
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cursor is advanced. Its function is simi- 
lar to that of putchar (see putc{3S)). At 
the right margin, an automatic newline is 
performed. At the bottom of the scrol- 
ling region, if scrollokQ is enabled, the 
scrolling region will be scrolled up one 
line. 

If ch is a tab, newline, or backspace, the 
cursor will be moved appropriately within 
the window. A newline also does a 
clrtoeolQ before moving. Tabs are con- 
sidered to be at every eighth column. If 
ch is another control character, it will be 
drawn in the "X notation. (Calling 
winch() after adding a control character 
will not return the control character, but 
instead will return the representation of 
the control character.) 

Video attributes can be combined with a 
character by or-ing them into the param- 
eter. This will result in these attributes 
also being set. (The intent here is that 
text, including attributes, can be copied 
from one place to another using inch() 
and addchQ.) See standoutQ, below. 

Note that ch is actually of type chtype, 
not a character. 

Note that addchQ, mvaddchQ, and 
mvwaddchQ, are macros. 

echochar(ch) 
wechochar(win, ch) 

pechochar(pad, ch) These routines are functionally 
equivalent to a call to addch(ch) fol- 
lowed by a call to refresh (), a call to 
waddch(win, ch) followed by a call to 
wrefresh(win), or a call to waddch(pad, 
ch) followed by a call to prefresh(pad). 
The knowledge that only a single charac- 
ter is being output is taken into 
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consideration and, for non-control char- 
acters, a considerable performance gain 
can be seen by using these routines 
instead of their equivalents. In the case 
of pechocharQ, the last location of the 
pad on the screen is reused for the 
arguments to prefreshQ. 

Note that ch is actually of type chtype, 
not a character. 

Note that echochar() is a macro. 

addstr(str) 
waddstr(win, str) 
mvwaddstr(win, y, x, str) 

mvaddstr(y, x, str) These routines write all the characters of 
the null-terminated character string str 
on the given window. This is equivalent 
to calling waddch() once for each char- 
acter in the string. 

Note that addstr(), mvaddstr(), and 
mvwaddstrQ are macros. 

attroff(attrs) 
wattroff(win, attrs) 
attron(attrs) 
wattron(win, attrs) 
attrset(attrs) 
wattrset(win, attrs) 
standendQ 
wstandend(win) 
standout () 

wstandout(win) These routines manipulate the current 
attributes of the named window. These 
attributes can be any combination of 
A STANDOUT, A REVERSE, A BOLD, 
A DIM, A BLINK, A UNDERLINE, and 
A ALTCHARSET. These constants are 
defined in < curses. h> and can be 
combined with the C logical OR ( | ) 
operator. 

The current attributes of a window are 
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applied to all characters that are written 
into the window with waddch(). Attri- 
butes are a property of the character, 
and move with the character through 
any scrolling and insert/delete 
line/character operations. To the extent 
possible on the particular terminal, they 
will be displayed as the graphic rendition 
of the characters put on the screen. 

attrset(attrs) sets the current attributes 
of the given window to attrs. 
attroff(attrs) turns off the named attri- 
butes without turning on or off any other 
attributes, attron (attrs) turns on the 
named attributes without affecting any 
others. standout() is the same as 
attron (A_ST AN DOUT). standendQ is 
the same as attrset (0), that is, it turns 
off all attributes. 

Note that attrs is actually of type 
chtype, not a character. 

Note that attroff(), attronQ, attrset(), 
standendQ, and standoutQ are macros. 

beep() 

flash () These routines are used to signal the ter- 

minal user. beep() will sound the audi- 
ble alarm on the terminal, if possible, 
and if not, will flash the screen (visible 
bell), if that is possible, flash () will flash 
the screen, and if that is not possible, 
will sound the audible signal. If neither 
signal is possible, nothing will happen. 
Nearly all terminals have an audible sig- 
nal (bell or beep) but only some can 
flash the screen. 

box(win, vertch, horch) 

A box is drawn around the edge of the 
window, win. vertch and horch are the 
characters the box is to be drawn with. 
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erase () 
werase(win) 



clear () 
wclear(win) 



If vertch and horch are 0, then appropri- 
ate default characters, ACS VLINE and 
ACSHLINE, will be used. 

Note that vertch and horch are actually 
of type chtype, not characters. 

These routines copy blanks to every 
position in the window. 

Note that erase() is a macro. 

These routines are like erase() and 
werase(), but they also call clearokQ, 
arranging that the screen will be cleared 
completely on the next call to 
wrefreshQ for that window, and 
repainted from scratch. 

Note that clear () is a macro. 

All lines below the cursor in this window 
are erased. Also, the current line to the 
right of the cursor, inclusive, is erased. 

Note that clrtobotQ is a macro. 

The current line to the right of the cur- 
sor, inclusive, is erased. 

Note that clrtoeolQ is a macro. 

Insert a ms millisecond pause in the out- 
put. It is not recommended that this 
routine be used extensively, because 
padding characters are used rather than 
a processor pause. 

delch() 
wdelch(win) 
mvdelch(y, x) 

mvwdelch(win, y, x) The character under the cursor in the 
window is deleted. All characters to the 



clrtobotQ 
wclrtobot(win) 



clrtoeolQ 
wclrtoeol(win) 



delayoutput(ms) 
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right on the same line are moved to the 
left one position and the last character 
on the line is filled with a blank. The cur- 
sor position does not change (after mov- 
ing to (y, x), if specified). (This does not 
imply use of the hardware "delete- 
character" feature.) 



Note that delch(), mvdelch(), 
mvwdelchQ are macros. 



and 



deleteln() 
wdeleteln(win) 



getyx(win, y, x) 



The line under the cursor in the window 
is deleted. All lines below the current 
line are moved up one line. The bottom 
line of the window is cleared. The cursor 
position does not change. (This does 
not imply use of the hardware "delete- 
line" feature.) 

Note that deletelnQ is a macro. 

The cursor position of the window is 
placed in the two integer variables y and 
x. This is implemented as a macro, so 
no "&" is necessary before the vari- 
ables. 

Like getyxQ, these routines store the 
current beginning coordinates and size 
of the specified window. 

Note that getbegyx() and getmaxyxQ 

are macros. 

insch(ch) 
winsch(win, ch) 
mvwinsch(win, y, x, ch) 

mvinsch(y, x, ch) The character ch is inserted before the 
character under the cursor. All charac- 
ters to the right are moved one space to 
the right, possibly losing the rightmost 
character of the line. The cursor posi- 
tion does not change (after moving to (y, 



getbegyx(win, y, x) 
getmaxyx(win, y, x) 
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x), if specified). (This does not imply use 
of the hardware "insert-character" 
feature.) 

Note that ch is actually of type chtype, 
not a character. 

Note that insch(), mvinsch(), and 
mvwinsch() are macros. 

insertlnQ 

winsertln(win) A blank line is inserted above the current 
line and the bottom line is lost. (This 
does not imply use of the hardware 
"insert-line" feature.) 

Note that insertlnQ is a macro. 

move(y, x) 

wmove(win, y, x) The cursor associated with the window is 
moved to line (row) y, column x. This 
does not move the physical cursor of the 
terminal until refresh() is called. The 
position specified is relative to the upper 
left corner of the window, which is (0, 0). 

Note that move() is a macro. 

overlay(srcwin, dstwin) 

overwrite(srcwin, dstwin) 

These routines overlay srcwin on top of 
dstwin; that is, all text in srcwin is 
copied into dstwin. scrwin and dstwin 
need not be the same size; only text 
where the two windows overlap is 
copied. The difference is that overlayQ 
is non-destructive (blanks are not 
copied), while overwriteQ is destructive. 

copywin (srcwin, dstwin, sminrow, smincol, dminrow, 
dmincol, dmaxrow, dmaxcol, overlay) 

This routine provides a finer grain of 
control over the overlay() and 
overwriteQ routines. Like in the 
prefreshQ routine, a rectangle is speci- 
fied in the destination window, (dminrow, 
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dmincol) and {dmaxrow, dmaxcol), and 
the upper-left-corner coordinates of the 
source window, (sminrow, smincol). If 
the argument overlay is true, then copy- 
ing is non-destructive, as in overlay (). 

printw(fmt [, arg. . .]) 

wprintw(win, fmt [, arg . .]) 

mvprintw(y, x, fmt [, arg . . .]) 

mvwprintw(win, y, x, fmt [, arg. . .]) 

These routines are analogous to 
printf(3). The string which would be out- 
put by printf(3) is instead output using 
waddstrQ on the given window. 

vwprintw(win, fmt, varglist) 

This routine corresponds to vfprintf (3S). 
It performs a wprintwQ using a variable 
argument list. The third argument is a 
vajist, a pointer to a list of arguments, 
as defined in <varargs.h>. See the 
vprintf (3S) and varargs(5) manual pages 
for a detailed description on how to use 
variable argument lists. 

scroll(win) The window is scrolled up one line. This 

involves moving the lines in the window 
data structure. As an optimization, if the 
window is stdscr and the scrolling region 
is the entire window, the physical screen 
will be scrolled at the same time. 

touchwin(win) 

touchline(win, start, count) 

Throw away all optimization information 
about which parts of the window have 
been touched, by pretending that the 
entire window has been drawn on. This 
is sometimes necessary when using 
overlapping windows, since a change to 
one window will affect the other window, 
but the records of which lines have been 
changed in the other window will not 
reflect the change. touchline() only 
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pretends that count lines have been 
changed, beginning with line start . 

Input 
getchQ 
wgeteh(win) 
mvgetch(y, x) 

mvwgetch(win, y, x) A character is read from the terminal 
associated with the window. In NODE- 
LAY mode, if there is no input waiting, 
the value ERR is returned. In DELAY 
mode, the program will hang until the 
system passes text through to the pro- 
gram. Depending on the setting of 
cbreakQ, this will be after one character 
(CBREAK mode), or after the first new- 
line (NOCBREAK mode). In HALF- 
DELAY mode, the program will hang 
until a character is typed or the specified 
timeout has been reached. Unless noe- 
cho() has been set, the character will 
also be echoed into the designated win- 
dow. No refresh () will occur between 
the move() and the getch() done within 
the routines mvgetchQ and 
mvwgetchQ. 

When using getchQ, wgetchQ, 
mvgetchQ, or mvwgetch(), do not set 
both NOCBREAK mode (nocbreakQ) 
and ECHO mode (echoQ) at the same 
time. Depending on the state of the 
fry (7) driver when each character is 
typed, the program may produce 
undesirable results. 

If keypad (win, TRUE) has been called, 
and a function key is pressed, the token 
for that function key will be returned 
instead of the raw characters. (See 
keypad () under "Input Options Setting.") 
Possible function keys are defined in 
<curses.h> with integers beginning 
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with 0401, whose names begin with 
KEY_. If a character is received that 
could be the beginning of a function key 
(such as escape), curses will set a timer. 
If the remainder of the sequence is not 
received within the designated time, the 
character will be passed through, other- 
wise the function key value will be 
returned. For this reason, on many ter- 
minals, there will be a delay after a user 
presses the escape key before the 
escape is returned to the program. (Use 
by a programmer of the escape key for 
a single character routine is 
discouraged. Also see notimeoutQ 
below.) 

Note that getch(), mvgetchQ, and 
mvwgetch() are macros. 

getstr(str) 
wgetstr(win, str) 
mvgetstr(y, x, str) 
mvwgetstr(win, y, x, str) 

A series of calls to getch() is made, until 
a newline, carriage return, or enter key is 
received. The resulting value is placed in 
the area pointed at by the character 
pointer str. The user's erase and kill 
characters are interpreted. As in 
mvgetchQ, no refresh () is done 
between the move() and getstrQ within 
the routines mvgetstrQ and 
mvwgetstrQ. 

Note that getstrQ, mvgetstrQ, and 
mvwgetstrQ are macros. 

Throws away any typeahead that has 
been typed by the user and has not yet 
been read by the program. 

Place c back onto the input queue to be 
returned by the next call to wgetchQ. 



flushinpQ 
ungetch(c) 
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The character, of type chtype, at the 
current position in the named window is 
returned. If any attributes are set for 
that position, their values will be OR'ed 
into the value returned. The predefined 
constants A_C HART EXT and 
A_ATTRIBUTES, defined in 
<curses.h>, can be used with the C 
logical AND (&) operator to extract the 
character or attributes alone. 

Note that inch(), winch(), mvinch(), 
and mvwinch() are macros. 

scanw(fmt [, arg . . .]) 

wscanw(win, fmt [, arg . . .]) 

mvscanw(y, x, fmt [, arg . . .]) 

mvwscanw(win, y, x, fmt [, arg . . .]) 

These routines correspond to scanf(3S), 
as do their arguments and return values. 
wgetstr() is called on the window, and 
the resulting line is used as input for the 
scan. 

vwscanw(win, fmt, ap) 

This routine is similar to vwprintw() 
above in that performs a wscanwj) 
using a variable argument list. The third 
argument is a vajist, a pointer to a list 
of arguments, as defined in 
<varargs.h>. See the vprintf (3S) and 
varargs(5) manual pages for a detailed 
description on how to use variable argu- 
ment lists. 

Output Options Setting 

These routines set options within curses that deal with output. 
All options are initially FALSE, unless otherwise stated. It is 
not necessary to turn these options off before calling 
endwinQ. 



inch() 
winch (win) 
mvinch(y, x) 
mvwinch(win, y, x) 
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clearok(win, bf) If enabled (bf is TRUE), the next call to 
wrefresh() with this window will clear 
the screen completely and redraw the 
entire screen from scratch. This is use- 
ful when the contents of the screen are 
uncertain, or in some cases for a more 
pleasing visual effect. 

idlok(win, bf) If enabled (bf is TRUE), curses will con- 

sider using the hardware "insert/delete- 
line" feature of terminals so equipped. If 
disabled (bf is FALSE), curses will very 
seldom use this feature. (The 
"insert/delete-character" feature is 
always considered.) This option should 
be enabled only if your application 
needs "insert/delete-line", for example, 
for a screen editor. It is disabled by 
default because "insert/delete-line" 
tends to be visually annoying when used 
in applications where it isn't really 
needed. If "insert/delete-line" cannot be 
used, curses will redraw the changed 
portions of all lines. 

leaveok(win, bf) Normally, the hardware cursor is left at 
the location of the window cursor being 
refreshed. This option allows the cursor 
to be left wherever the update happens 
to leave it. It is useful for applications 
where the cursor is not used, since it 
reduces the need for cursor motions. If 
possible, the cursor is made invisible 
when this option is enabled. 

setscrreg(top, bot) 

wsetscrreg(win, top, bot) 

These routines allow the user to set a 
software scrolling region in a window. 
top and bot are the line numbers of the 
top and bottom margin of the scrolling 
region. (Line 0 is the top line of the win- 
dow.) If this option and scrollokQ are 
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enabled, an attempt to move off the bot- 
tom margin line will cause all lines in the 
scrolling region to scroll up one line. 
(Note that this has nothing to do with 
use of a physical scrolling region capa- 
bility in the terminal, like that in the DEC 
VT100. Only the text of the window is 
scrolled; if idlok() is enabled and the ter- 
minal has either a scrolling region or 
"insert/delete-line" capability, they will 
probably be used by the output rou- 
tines.) 

Note that setscrregQ and wsetscrregQ 

are macros. 

scrollok(win, bf) This option controls what happens when 
the cursor of a window is moved off the 
edge of the window or scrolling region, 
either from a newline on the bottom line, 
or typing the last character of the last 
line. If disabled (bf is FALSE), the cur- 
sor is left on the bottom line at the loca- 
tion where the offending character was 
entered. If enabled (bf is TRUE), 
wrefreshQ is called on the window, and 
then the physical terminal and window 
are scrolled up one line. (Note that in 
order to get the physical scrolling effect 
on the terminal, it is also necessary to 
call idlok().) 

nl() 

nonl() These routines control whether newline 

is translated into carriage return and 
linefeed on output, and whether return is 
translated into newline on input. Initially, 
the translations do occur. By disabling 
these translations using nonl(), curses is 
able to make better use of the linefeed 
capability, resulting in faster cursor 
motion. 
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Input Options Setting 

These routines set options within curses that deal with input. 
The options involve using ioctl(2) and therefore interact with 
curses routines. It is not necessary to turn these options off 
before calling endwin(). 

For more information on these options, see Chapter 10 of the 
Programmer's Guide. 

cbreakQ 

nocbreak() These two routines put the terminal into 

and out of CBREAK mode, respectively. 
In CBREAK mode, characters typed by 
the user are immediately available to the 
program and erase/kill character pro- 
cessing is not performed. When in 
NOCBREAK mode, the tty driver will 
buffer characters typed until a newline 
or carriage return is typed. Interrupt 
and flow-control characters are unaf- 
fected by this mode (see termio(7)). Ini- 
tially the terminal may or may not be in 
CBREAK mode, as it is inherited, there- 
fore, a program should call cbreak() or 
nocbreak() explicitly. Most interactive 
programs using curses will set CBREAK 
mode. 

Note that cbreakQ overrides raw(). See 
getch() under "Input" for a discussion of 
how these routines interact with echo() 
and noechoQ. 

echo() 

noechoQ These routines control whether charac- 

ters typed by the user are echoed by 
getchQ as they are typed. Echoing by 
the tty driver is always disabled, but ini- 
tially getch() is in ECHO mode, so char- 
acters typed are echoed. Authors of 
most interactive programs prefer to do 
their own echoing in a controlled area of 
the screen, or not to echo at all, so they 
disable echoing by calling noechoQ. 
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halfdelay(tenths) 



intrflush(win, bf) 



keypad (win, bf) 



meta(win, bf) 



See getch() under "Input" for a discus- 
sion of how these routines interact with 
cbreakQ and nocbreak(). 

Half-delay mode is similar to CBREAK 
mode in that characters typed by the 
user are immediately available to the 
program. However, after blocking for 
tenths tenths of seconds, ERR will be 
returned if nothing has been typed. 
tenths must be a number between 1 and 
255. Use nocbreak() to leave half-delay 
mode. 

If this option is enabled, when an inter- 
rupt key is pressed on the keyboard 
(interrupt, break, quit) all output in the 
tty driver queue will be flushed, giving 
the effect of faster response to the inter- 
rupt, but causing curses to have the 
wrong idea of what is on the screen. 
Disabling the option prevents the flush. 
The default for the option is inherited 
from the tty driver settings. The window 
argument is ignored. 

This option enables the keypad of the 
user's terminal. If enabled, the user can 
press a function key (such as an arrow 
key) and wgetch() will return a single 
value representing the function key, as 
in KEYJLEFT. If disabled, curses will 
not treat function keys specially and the 
program would have to interpret the 
escape sequences itself. If the keypad 
in the terminal can be turned on (made 
to transmit) and off (made to work 
locally), turning on this option will cause 
the terminal keypad to be turned on 
when wgetch() is called. 

If enabled, characters returned by 
wgetchQ are transmitted with all 8 bits, 
instead of with the highest bit stripped. 
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In order for meta() to work correctly, the 
km (has_meta_key) capability has to be 
specified in the terminal's terminfo(4) 
entry. 

nodelay(win, bf) This option causes wgetch() to be a 
non-blocking call. If no input is ready, 
wgetch() will return ERR. If disabled, 
wgetch() will hang until a key is 
pressed. 

notimeout(win, bf) While interpreting an input escape 
sequence, wgetchQ will set a timer while 
waiting for the next character. If 
notimeout(win, TRUE) is called, then 
wgetch() will not set a timer. The pur- 
pose of the timeout is to differentiate 
between sequences received from a 
function key and those typed by a user. 

raw() 

norawQ The terminal is placed into or out of raw 

mode. RAW mode is similar to CBREAK 
mode, in that characters typed are 
immediately passed through to the user 
program. The differences are that in 
RAW mode, the interrupt, quit, suspend, 
and flow control characters are passed 
through uninterpreted, instead of gen- 
erating a signal. RAW mode also causes 
8-bit input and output. The behavior of 
the BREAK key depends on other bits in 
the tty{7) driver that are not set by 
curses . 

typeahead(fildes) curses does "line-breakout optimization" 
by looking for typeahead periodically 
while updating the screen. If input is 
found, and it is coming from a tty, the 
current update will be postponed until 
refresh () or doupdateQ is called again. 
This allows faster response to com- 
mands typed in advance. Normally, the 
file descriptor for the input FILE pointer 
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passed to newterm(), or stdin in the 
case that initscr() was used, will be 
used to do this typeahead checking. 
The typeahead () routine specifies that 
the file descriptor fildes is to be used to 
check for typeahead instead. If fildes is 
-1, then no typeahead checking will be 
done. 



Note that fildes is a file descriptor, not a 
<stdio.h> FILE pointer. 



Environment Queries 



baud rate () 

char erasecharQ 

has_ic() 

hasjl() 



char killchar() 



char *longname() 



Returns the output speed of the termi- 
nal. The number returned is in bits per 
second, for example, 9600, and is an 
integer. 

The user's current erase character is 
returned. 

True if the terminal has insert- and 
delete-character capabilities. 

True if the terminal has insert- and 
delete-line capabilities, or can simulate 
them using scrolling regions. This might 
be used to check to see if it would be 
appropriate to turn on physical scrolling 
using scrollok(). 

The user's current line-kill character is 
returned. 

This routine returns a pointer to a static 
area containing a verbose description of 
the current terminal. The maximum 
length of a verbose description is 128 
characters. It is defined only after the 
call to initscrQ or newterm(). The area 
is overwritten by each call to newterm() 
and is not restored by set_term(), so 
the value should be saved between calls 
to newterm() if longnameQ is going to 
be used with multiple terminals. 
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Soft Labels 

If desired, curses will manipulate the set of soft function-key 
labels that exist on many terminals. For those terminals that 
do not have soft labels, if you want to simulate them, curses 
will take over the bottom line of stdscr, reducing the size of 
stdscr and the variable LINES, curses standardizes on 8 
labels of 8 characters each. 

slkjnit(labfmt) In order to use soft labels, this routine 
must be called before initscrQ or 
newtermQ is called. If initscrQ winds 
up using a line from stdscr to emulate 
the soft labels, then labfmt determines 
how the labels are arranged on the 
screen. Setting labfmt to 0 indicates 
that the labels are to be arranged in a 
3-2-3 arrangement; 1 asks for a 4-4 
arrangement. 

slk_set(labnum, label, labfmt) 

labnum is the label number, from 1 to 8. 
label is the string to be put on the label, 
up to 8 characters in length. A NULL 
string or a NULL pointer will put up a 
blank label, labfmt is one of 0, 1 or 2, to 
indicate whether the label is to be left- 
justified, centered, or right-justified 
within the label. 

slk_refresh() 

slk_noutrefresh() These routines correspond to the rou- 
tines wrefreshQ and wnoutrefreshQ. 
Most applications would use 
slknoutrefreshQ because a wrefreshQ 
will most likely soon follow. 

char *slk_label (labnum) 

The current label for label number lab- 
num, with leading and trailing blanks 
stripped, is returned. 

slk_clear() The soft labels are cleared from the 

screen. 
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slk_restore() The soft labels are restored to the 

screen after a slk_clear(). 

slk_touch() All of the soft labels are forced to be 

output the next time a slknoutrefreshQ 
is performed. 

Low-Level curses Access 

The following routines give low-level access to various curses 
functionality. These routines typically would be used inside of 
library routines. 

def_prog_mode() 

def_shell_mode() Save the current terminal modes as the 
"program" (in curses) or "shell" (not in 
curses) state for use by the 
reset_prog_mode() and 
reset_shell_mode() routines. This is 
done automatically by initscr(). 

reset_prog_mode ( ) 

reset_shell_mode() Restore the terminal to "program" (in 
curses) or "shell" (out of curses) state. 
These are done automatically by 
endwin() and doupdateQ after an 
endwin(), so they normally would not be 
called. 

These routines save and restore the 
state of the terminal modes. savettyQ 
saves the current state of the terminal in 
a buffer and resetty() restores the state 
to what it was at the last call to 
savettyQ. 

The current coordinates of the virtual 
screen cursor are returned in y and x. 
Like getyxQ, the variables y and x do 
not take an "&" before them. If 
leaveokQ is currently TRUE, then -1,-1 
will be returned. If lines may have been 
removed from the top of the screen 
using ripoffline() and the values are to 
be used beyond just passing them on to 



resetty() 
savetty() 



getsyx(y, x) 
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setsyx(y, x) 



ripoff line (line, init) 



setsyxQ, the value y + stdscr->_yoffset 

should be used for those other uses. 

Note that getsyxQ is a macro. 

The virtual screen cursor is set to y, x. If 
y and x are both -1, then leaveok() will 
be set. The two routines getsyxQ and 
setsyxQ are designed to be used by a 
library routine which manipulates curses 
windows but does not want to mess up 
the current position of the program's 
cursor. The library routine would call 
getsyxQ at the beginning, do its mani- 
pulation of its own windows, do a 
wnoutrefresh() on its windows, call set- 
syxQ, and then call doupdateQ. 

This routine provides access to the same 
facility that slk_init() uses to reduce the 
size of the screen. ripofflineQ must be 
called before initscr() or newtermQ is 
called. If line is positive, a line will be 
removed from the top of stdscr; if nega- 
tive, a line will be removed from the bot- 
tom. When this is done inside initscrQ, 
the routine init() is called with two argu- 
ments: a window pointer to the 1-line 
window that has been allocated and an 
integer with the number of columns in 
the window. Inside this initialization rou- 
tine, the integer variables LINES and 
COLS (defined in <curses.h>) are not 
guaranteed to be accurate and 
wrefreshQ or doupdateQ must not be 
called. It is allowable to call 
wnoutrefreshQ during the initialization 
routine. 

ripofflineQ can be called up to five 
times before calling initscrQ or 
newtermQ. 
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scrdump (filename) The current contents of the virtual 
screen are written to the file filename. 

scr_restore(filename) 

The virtual screen is set to the contents 
of filename, which must have been writ- 
ten using scr_dump(). The next call to 
doupdate() will restore the screen to 
what it looked like in the dump file. 

scrjnit(filename) The contents of filename are read in and 
used to initialize the curses data struc- 
tures about what the terminal currently 
has on its screen. If the data is deter- 
mined to be valid, curses will base its 
next update of the screen on this infor- 
mation rather than clearing the screen 
and starting from scratch. scr_init() 
would be used after initscrQ or a 
system (3S) call to share the screen with 
another process which has done a 
scr_dump() after its endwin() call. The 
data will be declared invalid if the time- 
stamp of the tty is old or the terminfo(4) 
capability nrrmc is true. 

curs_set(visibility) The cursor is set to invisible, normal, or 
very visible for visibility equal to 0, 1 or 
2. 

draino(ms) Wait until the output has drained enough 

that it will only take ms more mil- 
liseconds to drain completely. 

garbagedlines(win, begline, numlines) 

This routine indicates to curses that a 
screen line is garbaged and should be 
thrown away before having anything 
written over the top of it. It could be 
used for programs such as editors which 
want a command to redraw just a single 
line. Such a command could be used in 
cases where there is a noisy communica- 
tions line and redrawing the entire 
screen would be subject to even more 
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communication noise. Just redrawing 
the single line gives some semblance of 
hope that it would show up unblem- 
ished. The current location of the win- 
dow is used to determine which lines are 
to be redrawn. 

napms(ms) Sleep for ms milliseconds. 

Terminfo-Level Manipulations 

These low-level routines must be called by programs that need 
to deal directly with the terminfo{A) database to handle certain 
terminal capabilities, such as programming function keys. For 
all other functionality, curses routines are more suitable and 
their use is recommended. 

Initially, setupterm() should be called. (Note that setupterm() 
is automatically called by initscr() and newterm().) This will 
define the set of terminal-dependent variables defined in the 
terminfo(A) database. The terminfo(4) variables lines and 
columns (see terminfo(A)) are initialized by setupterm() as fol- 
lows: if the environment variables LINES and COLUMNS 
exist, their values are used. If the above environment vari- 
ables do not exist and the program is running in a layer (see 
/ayers(1)), the size of the current layer is used. Otherwise, the 
values for lines and columns specified in the terminfo{4) data- 
base are used. 

The header files <curses.h> and <term.h> should be 
included, in this order, to get the definitions for these strings, 
numbers, and flags. Parameterized strings should be passed 
through tparm() to instantiate them. All terminfo{4) strings 
(including the output of tparm()) should be printed with 
tputs() or putp(). Before exiting, reset_shell_mode() should 
be called to restore the tty modes. Programs which use cur- 
sor addressing should output enter_ca_mode upon startup 
and should output exitcamode before exiting (see ter- 
minfo(4)). (Programs desiring shell escapes should call 
reset_shell_mode() and output exit_ca_mode before the shell 
is called and should output enter_ca_mode and call 
reset_prog_mode() after returning from the shell. Note that 
this is different from the curses routines (see endwinQ). 
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setupterm(term, fildes, errret) 

Reads in the terminfo (4) database, initial- 
izing the terminfo(A) structures, but does 
not set up the output virtualization struc- 
tures used by curses. The terminal type 
is in the character string term; if term is 
NULL, the environment variable TERM 
will be used. All output is to the file 
descriptor fildes. If errret is not NULL, 
then setupterm() will return OK or ERR 
and store a status value in the integer 
pointed to by errret. A status of 1 in 
errret is normal, 0 means that the termi- 
nal could not be found, and -1 means 
that the terminfo (4) database could not 
be found. If errret is NULL, setupterm () 
will print an error message upon finding 
an error and exit. Thus, the simplest call 
is setupterm ((char *)0, 1, (int *)0), 
which uses all the defaults. 

The terminfo (4) boolean, numeric and 
string variables are stored in a structure 
of type TERMINAL. After setupterm () 
returns successfully, the variable 
curterm (of type TERMINAL *) is ini- 
tialized with all of the information that 
the terminfo (4) boolean, numeric and 
string variables refer to. The pointer 
may be saved before calling setup- 
term () again. Further calls to setup- 
term () will allocate new space rather 
than reuse the space pointed to by 
curterm. 

set_curterm(nterm) nterm is of type TERMINAL *. 

set_curterm() sets the variable cur_term 
to nterm, and makes all of the ter- 
minfo (4) boolean, numeric and string 
variables use the values from nterm. 

del_curterm(oterm) oterm is of type TERMINAL *. 

del_curterm() frees the space pointed 



Page 36 



UP-13712 



CURSES (3X) 



to by oterm and makes it available for 
further use. If oterm is the same as 
cur_term, then references to any of the 
terminfo(4) boolean, numeric and string 
variables thereafter may refer to invalid 
memory locations until another setup- 
term () has been called. 

restartterm(term, fildes, errret) 

Like setupterm() after a memory 
restore. 

char *tparm(str, p v p 2 p g ) 

Instantiate the string str with parms pj. 
A pointer is returned to the result of str 
with the parameters applied. 

tputs(str, count, putc) 

Apply padding to the string str and out- 
put it. str must be a terminfo(4) string 
variable or the return value from 
tparm(), tgetstrQ, tigetstr() or tgoto(). 
count is the number of lines affected, or 
1 if not applicable. putc() is a 
pi/fchar (3S)-like routine to which the 
characters are passed, one at a time. 

putp(str) A routine that calls tputs {str, 1, 

putchar()). 

vidputs(attrs, putc) Output a string that puts the terminal in 
the video attribute mode attrs, which is 
any combination of the attributes listed 
below. The characters are passed to the 
putchar (3S)-like routine putc(). 

vidattr (attrs) Like vidputs(), except that it outputs 

through putchar (3S). 

mvcur(oldrow, oldcol, newrow, newcol) 

Low-level cursor motion. 

The following routines return the value of the capability 
corresponding to the terminfo(4) capname passed to them, 
such as xenl. 
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tigetflag(capname) The value -1 is returned if capname is 
not a boolean capability. 

tigetnum (capname) The value -2 is returned if capname is 
not a numeric capability. 

tigetstr (capname) The value (char *) -1 is returned if cap- 
name is not a string capability. 

char *boolnames[], *boolcodes[], *boolfnames[] 
char *numnames[], *numcodes[], *numfnames[] 
char *strnames[], *strcodes[], *strf names [] 

These null-terminated arrays contain the 
capnames, the termcap codes, and the 
full C names, for each of the terminfo(4) 
variables. 

Termcap Emulation 

These routines are included as a conversion aid for programs 
that use the termcap library. Their parameters are the same 
and the routines are emulated using the terminfo(4) database. 

tgetent(bp, name) Look up termcap entry for name. The 
emulation ignores the buffer pointer bp. 

tgetflag(codename) Get the boolean entry for codename. 

tgetnum (codes) Get numeric entry for codename. 

char *tgetstr(codename, area) 

Return the string entry for codename. If 
area is not NULL, then also store it in 
the buffer pointed to by area and 
advance area. tputsQ should be used 
to output the returned string. 

char *tgoto(cap, col, row) 

Instantiate the parameters into the given 
capability. The output from this routine 
is to be passed to tputsQ. 

tputs(str, affcnt, putc) 

See tputsQ above, under "Terminfo- 
Level Manipulations". 

Miscellaneous 
traceoffQ 
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traceonQ Turn off and on debugging trace output 

when using the debug version of the 
curses library, /usr/lib/libdcurses.a. This 
facility is available only to customers 
with a source license. 

unctrl(c) This macro expands to a character string 

which is a printable representation of the 
character c. Control characters are 
displayed in the "X notation. Printing 
characters are displayed as is. 

unctrl() is a macro, defined in 
<unctrl.h>, which is automatically 
included by <curses.h>. 

A character string corresponding to the 
key c is returned. 

This routine is one of the few that is to 
be called before initscrQ or newterm() 
is called. It arranges things so that 
curses thinks that there is a 1-line 
screen, curses will not use any terminal 
capabilities that assume that they know 
what line on the screen the cursor is on. 

Use of cursor 

The special window cursor can be used in only a few routines. 
If the window argument to clearok() is curscr, the next call to 
wrefresh() with any window will cause the screen to be 
cleared and repainted from scratch. If the window argument 
to wrefreshQ is curscr, the screen is immediately cleared and 
repainted from scratch. (This is how most programs would 
implement a "repaint-screen" routine.) The source window 
argument to overlayQ, overwriteQ, and copywin() may be 
curscr, in which case the current contents of the virtual termi- 
nal screen will be accessed. 

Obsolete Calls 

Various routines are provided to maintain compatibility in pro- 
grams written for older versions of the curses library. These 
routines are all emulated as indicated below. 



char *keyname(c) 
filter() 
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crmode() 

fixterm() 

gettmode() 

nocrmode() 

resettermQ 

saveterm() 

setterm() 



Replaced by cbreakQ. 
Replaced by reset_prog_mode(). 
A no-op. 

Replaced by nocbreak(). 
Replaced by resetshellmodeQ. 
Replaced by def_prog_mode(). 
Replaced by setupterm(). 



ATTRIBUTES 

The following video attributes, defined in <curses.h>, can be 
passed to the routines attronQ, attroff(), and attrsetQ, or 
OR'ed with the characters passed to addch(). 



A 


STANDOUT 


Terminal's best highlighting mode 


A 


"underline 


Underlining 


a" 


"reverse 


Reverse video 


a" 


"blink 


Blinking 


a" 


"dim 


Half bright 


a" 


"bold 


Extra bright or bold 


a] 


altcharset 


Alternate character set 


A 


CHARTEXT 


Bit-mask to extract character (see winch ()) 


a" 


"attributes 


Bit-mask to extract attributes (see winchQ) 


a" 


"normal 


Bit mask to reset all attributes off 






(for example: attrset (A_NORMAL) 



FUNCTION-KEYS 

The following function keys, defined in <curses.h>, might be 
returned by getch() if keypad () has been enabled. Note that 
not all of these may be supported on a particular terminal if 
the terminal does not transmit a unique code when the key is 
pressed or the definition for the key is not present in the ter- 
minfo{A) database. 



Name 

KEYBREAK 
KEYDOWN 
KEY_UP 
KEY_LEFT 
KEY RIGHT 



Value 

0401 
0402 
0403 
0404 
0405 



Key name 

break key (unreliable) 
The four arrow keys . . 
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KEY_HOME 


0406 


KEY BACKSPACE 


0407 


KEY_FO 


0410 


r\LY r\r\) 


(r\tY rU + (n)j 


KEY DL 


0510 


KEY IL 


0511 


KEY DC 


0512 


KEYJC 


0513 


KEY_EIC 


0514 


KbY OLEAR 


0515 


KEY EOS 


0516 


KEY EOL 


0517 


KEY SF 


0520 


KEY_SR 


0521 


KEY NPAGE 


0522 


KEY PPAGE 


0523 


KEY STAB 


0524 


KEY CTAB 


0525 


KEY CATAB 


0526 


KEY ENTER 


0527 


KEY SRESET 


0530 


KEY RESET 


0531 


KEY PRINT 


0532 


KEY LL 


0533 



KEY_A1 0534 

KEYA3 0535 

KEY_B2 0536 

KEY_C1 0537 

KEY_C3 0540 

KEY_BTAB 0541 

KEY_BEG 0542 

KEYCANCEL 0543 

KEY_CLOSE 0544 



Home key 

(upward + left arrow) 

backspace (unreliable) 

Function keys. Space for 

64 keys is reserved. 

Formula for f p . 

Delete line 

Insert line 

Delete character 

Insert char or enter 

insert mode 

Exit insert char mode 

Clear screen 

Clear to end of screen 

Clear to end of line 

Scroll 1 line forward 

Scroll 1 line backwards 

(reverse) 

Next page 

Previous page 

Set tab 

Clear tab 

Clear all tabs 

Enter or send 

soft (partial) reset 

reset or hard reset 

print or copy 

home down or bottom 

(lower left) 

keypad is arranged like this: 

A1 up A3 

left B2 right 

C1 down C3 
Upper left of keypad 
Upper right of keypad 
Center of keypad 
Lower left of keypad 
Lower right of keypad 
Back tab key 
beg(inning) key 
cancel key 
close key 
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KEY 


COMMAND 


0545 


cmd (command) key 


KEY] 


_COPY 


0546 


copy key 


key" 


CREATE 


0547 


create key 


key" 


"end 


0550 


end key 


key" 


"exit 


0551 


exit key 


key" 


"find 


0552 


find key 


key" 


"help 


0553 


help key 


key] 


MARK 


0554 


mark key 


key] 


.MESSAGE 


0555 


message key 


key" 


MOVE 


0556 


move key 


key" 


"next 


0557 


next object key 


key" 


"open 


0560 


open key 


key" 


OPTIONS 


0561 


options key 


key" 


"previous 


0562 


previous object key 


key" 


"redo 


0563 


redo key 


key" 


REFERENCE 


0564 


ref(erence) key 


key] 


REFRESH 


0565 


refresh key 


key" 


REPLACE 


0566 


replace key 


key" 


"RESTART 


0567 


restart key 


key] 


RESUME 


0570 


resume key 


key" 


SAVE 


0571 


save key 


key" 


SBEG 


0572 


shifted beginning key 


key" 


SCANCEL 


0573 


shifted cancel key 


key" 


SCOMMAND 


0574 


shifted command key 


key" 


"SCOPY 


0575 


shifted copy key 


key" 


"SCREATE 


0576 


shifted create key 


key" 


"SDC 


0577 


shifted delete char key 


key" 


SDL 


0600 


shifted delete line key 


key] 


SELECT 


0601 


select key 


key" 


"send 


0602 


shifted end key 


key] 


]SEOL 


0603 


shifted clear line key 


key" 


SEXIT 


0604 


shifted exit key 


key] 


]sfind 


0605 


shifted find key 


KEY_ 


SHELP 


0606 


shifted help key 


key] 


]SHOME 


0607 


shifted home key 


key] 


]sic 


0610 


shifted input key 


key] 


SLEFT 


0611 


shifted left arrow key 


key 


SMESSAGE 


0612 


shifted message key 


key" 


"SMOVE 


0613 


shifted move key 


key" 


SNEXT 


0614 


shifted next key 


KEY 


SOPTIONS 


0615 


shifted options key 


key" 


SPREVIOUS 


0616 


shifted prev key 
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KEY 
KEY 
KEY 
KEY 
KEY 
KEY 
KEY 

key" 
key" 
key" 



SPRINT 
SREDO 



0617 
0620 
0621 
0622 
0623 
0624 
0625 
0626 
0627 
0630 



shifted print key 
shifted redo key 
shifted replace key 
shifted right arrow 
shifted resume key 
shifted save key 
shifted suspend key 
shifted undo key 
suspend key 
undo key 



SREPLACE 



SRIGHT 

SRSUME 

SSAVE 



SSUSPEND 
SUNDO 
"SUSPEND 
UNDO 



LINE GRAPHICS 

The following variables may be used to add line-drawing char- 
acters to the screen with waddchQ. When defined for the ter- 
minal, the variable will have the A_ALTCHARSET bit turned 
on. Otherwise, the default charcter listed below will be stored 
in the variable. The names were chosen to be consistent with 
the DEC VT100 nomenclature. 

Name Default Glyph Description 



ACS 


ULCORNER 


+ 


upper left corner 


ACS 


LLCORNER 


+ 


lower left corner 


ACS 


URCORNER 


+ 


upper right corner 


ACS 


LRCORNER 


+ 


lower right corner 


ACS 


RTEE 


+ 


right tee (■] ) 


ACS 


LTEE 


+ 


left tee {\-) 


ACS 


BTEE 


+ 


bottom tee (|_) 


ACS 


TTEE 


+ 


top tee (| ) 


ACS 


HLINE 




horizontal line 


ACS 


VLINE 


! 


vertical line 


ACS 


"plus 


+ 


plus 


ACS 


S1 




scan line 1 


ACS 


S9 




scan line 9 


ACS 


DIAMOND 


+ 


diamond 


ACS 


CKBOARD 




checker board (stipple) 


ACS 


"degree 




degree symbol 


ACS 


"PLMINUS 


# 


plus/minus 


ACS 


"bullet 


0 


bullet 


ACS 


larrow 


< 


arrow pointing left 


ACS 


"rarrow 


> 


arrow pointing right 


ACS 


"darrow 


V 


arrow pointing down 


ACS 


"UARROW 




arrow pointing up 
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ACSBOARD 
ACS_LANTERN 
ACS BLOCK 



# 
# 
# 



board of squares 
lantern symbol 
solid square block 



RETURN VALUES 

All routines return the integer OK upon successful completion 
and the integer ERR upon failure, unless otherwise noted in 
the preceding routine descriptions. 

All macros return the value of their w version, except 
setscrreg(), wsetscrregQ, getsyxQ, getyx(), getbegy(), get- 
maxyx(). For these macros, no useful value is returned. 

Routines that return pointers always return (type *) NULL on 
error. 



Currently typeahead checking is done using a nodelay read 
followed by an ungetchQ of any character that may have 
been read. Typeahead checking is done only if wgetchQ has 
been called at least once. This will be changed when proper 
kernel support is available. Programs which use a mixture of 
their own input routines with curses input routines may wish 
to call typeahead(-l) to turn off typeahead checking. 

The argument to napms() is currently rounded up to the 
nearest second. 

draino (ms) only works for ms equal to 0. 
WARNINGS 

To use the new curses features, use the Release 3.0 version of 
curses on UNIX System Release 3.0. All programs that ran 
with System V Release 2 curses will run with System V 
Release 3.0. You may link applications with object files based 
on the Release 2 curses /terminfo with the Release 3.0 
libcurses.a library. You may link applications with object files 
based on the Release 3.0 curses /terminfo with the Release 2 
libcurses.a library, so long as the application does not use the 
new features in the Release 3.0 curses I terminfo. 

The plotting library plot{3X) and the curses library curses (3X) 
both use the names erase() and move(). The curses versions 
are macros. If you need both libraries, put the p/of(3X) code 
in a different source file than the curses (3X) code, and/or 
#undef move() and erase() in the plot (3X) code. 



BUGS 
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Between the time a call to initscrQ and endwinQ has been 
issued, use only the routines in the curses library to generate 
output. Using system calls or the "standard I/O package" (see 
stdio (3S)) for output during that time can cause unpredictable 
results. 

SEE ALSO 

cc(1), ld(1), ioctl(2), plot(3X), putc(3S), scanf(3S), stdio(3S), 
system (3S), vprintf(3S), profile(4), term (4), terminfo(4), 
varargs(5). 

termio(7), tty(7) in the System Administrator's Reference 
Manual. 

Chapter 10 of the Programmer's Guide. 
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NAME 

directory: opendir, readdir, telldir, seekdir, rewinddir, closedir - 
directory operations 

SYNOPSIS 

#include < sys/types.h > 
#include <dirent.h> 

DIR *opendir (filename) 
char ^filename; 

struct dirent *readdir (dirp) 
DIR *dirp; 

long telldir (dirp) 
DIR *dirp; 

void seekdir (dirp, loc) 
DIR *dirp; 
long loc; 

void rewinddir (dirp) 
DIR *dirp; 

void closedir(dirp) 
DIR *dirp; 

DESCRIPTION 

Opendir opens the directory named by filename and associ- 
ates a directory stream with it. Opendir returns a pointer to 
be used to identify the directory stream in subsequent opera- 
tions. The pointer NULL is returned if filename cannot be 
accessed or is not a directory, or if it cannot malloc(3X) 
enough memory to hold a DIR structure or a buffer for the 
directory entries. 

Readdir returns a pointer to the next active directory entry. 
No inactive entries are returned. It returns NULL upon reach- 
ing the end of the directory or upon detecting an invalid loca- 
tion in the directory. 

Telldir returns the current location associated with the named 
directory stream. 

Seekdir sets the position of the next readdir operation on the 
directory stream. The new position reverts to the one associ- 
ated with the directory stream when the telldir operation from 
which loc was obtained was performed. Values returned by 
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telldir are good only if the directory has not changed due to 
compaction or expansion. This is not a problem with System 
V, but it may be with some file system types. 

Rewinddir resets the position of the named directory stream 
to the beginning of the directory. 

Closedir closes the named directory stream and frees the DIR 
structure. 

The following errors can occur as a result of these operations. 
opendir: 

[ENOTDIR] A component of filename is not a directory. 

[EACCES] A component of filename denies search per- 
mission. 

[EMFILE] The maximum number of file descriptors are 
currently open. 

[EFAULT] Filename points outside the allocated address 
space. 

readdir: 

[ENOENT] The current file pointer for the directory is not 
located at a valid entry. 

[EBADF] The file descriptor determined by the DIR 

stream is no longer valid. This results if the 
DIR stream has been closed. 

telldir, seekdir, and closedir: 

[EBADF] The file descriptor determined by the DIR 

stream is no longer valid. This results if the 
DIR stream has been closed. 

EXAMPLE 

Sample code which searches a directory for entry name: 

dirp = opendir( "." ); 
while ( (dp = readdir( dirp )) != NULL ) 
if ( strcmp( dp- > d name, name ) = = 0 ) 

{ 

closedir( dirp ); 
return FOUND; 
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} 

closedir( dirp ); 
return NOTJOUND; 

SEE ALSO 

getdents(2), dirent(4). 

WARNINGS 

Rewinddir is implemented as a macro, so its function address 
cannot be taken. 
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NAME 

Idahread - read the archive header of a member of an archive 
file 

SYNOPSIS 

#include <stdio.h> 
#include <ar.h> 
#include <filehdr.h> 
#include <ldfcn.h> 



int Idahread (Idptr, arhead) 
LDFILE *ldptr; 
ARCHDR *arhead; 

DESCRIPTION 

If TYPE(/dpfr) is the archive file magic number, Idahread reads 
the archive header of the common object file currently associ- 
ated with Idptr into the area of memory beginning at arhead. 

Idahread returns SUCCESS or FAILURE. Idahread will fail if 
TYPE(/dpfr) does not represent an archive file, or if it cannot 
read the archive header. 

The program must be loaded with the object file access rou- 
tine library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldfcn(4), ar(4). 
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NAME 

Idclose, Idaclose - close a common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int Idclose (Idptr) 
LDFILE *ldptr; 

int Idaclose (Idptr) 
LDFILE *ldptr; 

DESCRIPTION 

Ldopen{3X) and Idclose are designed to provide uniform 
access to both simple object files and object files that are 
members of archive files. Thus an archive of common object 
files can be processed as if it were a series of simple common 
object files. 

If TYPE(ldptr) does not represent an archive file, Idclose will 
close the file and free the memory allocated to the LDFILE 
structure associated with Idptr. If JYPE(ldptr) is the magic 
number of an archive file, and if there are any more files in the 
archive, Idclose will reinitialize OFFSET(/cfpfr) to the file 
address of the next archive member and return FAILURE. 
The LDFILE structure is prepared for a subsequent 
ldopen{3X). In all other cases, Idclose returns SUCCESS. 

Ldaclose closes the file and frees the memory allocated to the 
LDFILE structure associated with Idptr regardless of the value 
of JYPE(ldptr). Ldaclose always returns SUCCESS. The 
function is often used in conjunction with Idaopen. 

The program must be loaded with the object file access rou- 
tine library libld.a. 

SEE ALSO 

fclose(3S), ldopen(3X), ldfcn(4). 
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NAME 

Idfhread - read the file header of a common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int Idfhread (Idptr, filehead) 
LDFILE *ldptr; 
FILHDR *filehead; 

DESCRIPTION 

Idfhread reads the file header of the common object file 
currently associated with Idptr into the area of memory begin- 
ning at filehead. 

Idfhread returns SUCCESS or FAILURE. Idfhread will fail if it 
cannot read the file header. 

In most cases the use of Idfhread can be avoided by using the 
macro HEADERf/dpf/") defined in Idfcn.h [see Idfcn (4)]. The 
information in any field, fieldname, of the file header may be 
accessed using HEADER (Idptr) .fieldname. 

The program must be loaded with the object file access rou- 
tine library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), Idfcn (4). 
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NAME 

Idgetname - retrieve symbol name for common object file 
symbol table entry 

SYNOPSIS 

#include <stdio.h> 
#include <filehdr.h> 
#include <syms.h> 
#include <ldfcn.h> 

char *ldgetname (Idptr, symbol) 
LDFILE *ldptr; 
SYMENT *symbol; 

DESCRIPTION 

Idgetname returns a pointer to the name associated with sym- 
bol as a string. The string is contained in a static buffer local 
to Idgetname that is overwritten by each call to Idgetname, 
and therefore must be copied by the caller if the name is to 
be saved. 

Idgetname can be used to retrieve names from object files 
without any backward compatibility problems. Idgetname will 
return NULL (defined in stdio.h) for an object file if the name 
cannot be retrieved. This situation can occur: 

if the "string table" cannot be found, 

if not enough memory can be allocated for the string 
table, 

if the string table appears not to be a string table (for 
example, if an auxiliary entry is handed to Idgetname that 
looks like a reference to a name in a nonexistent string 
table), or 

if the name's offset into the string table is past the end of 
the string table. 

Typically, Idgetname will be called immediately after a suc- 
cessful call to Idtbread to retrieve the name associated with 
the symbol table entry filled by Idtbread. 

The program must be loaded with the object file access rou- 
tine library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldtbread(3X), ldtbseek(3X), ldfcn(4). 
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NAME 

Idlread, Idlinit, Idlitem - manipulate line number entries of a 
common object file function 

SYNOPSIS 

#include <stdio.h> 
#include <filehdr.h> 
#include < linenum.h> 
#include <ldfcn.h> 

int ldlread(ldptr, fcnindx, linenum, linent) 

LDFILE *ldptr; 

long fcnindx; 

unsigned short linenum; 

LINENO *linent; 

int ldlinit(ldptr, fcnindx) 
LDFILE *ldptr; 
long fcnindx; 

int ldlitem(ldptr, linenum, linent) 
LDFILE *ldptr; 
unsigned short linenum; 
LINENO *linent; 

DESCRIPTION 

Idlread searches the line number entries of the common 
object file currently associated with Idptr. Idlread begins its 
search with the line number entry for the beginning of a func- 
tion and confines its search to the line numbers associated 
with a single function. The function is identified by fcnindx, 
the index of its entry in the object file symbol table. Idlread 
reads the entry with the smallest line number equal to or 
greater than linenum into the memory beginning at linent. 

Ldlinit and Idlitem together perform exactly the same function 
as Idlread. After an initial call to Idlread or Idlinit, Idlitem may 
be used to retrieve a series of line number entries associated 
with a single function. Ldlinit simply locates the line number 
entries for the function identified by fcnindx. Ldlitem finds and 
reads the entry with the smallest line number equal to or 
greater than linenum into the memory beginning at linent. 

Idlread, Idlinit, and Idlitem each return either SUCCESS or 
FAILURE. Idlread will fail if there are no line number entries 
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in the object file, if fcnindx does not index a function entry in 
the symbol table, or if it finds no line number equal to or 
greater than linenum. Ldlinit will fail if there are no line 
number entries in the object file or if fcnindx does not index a 
function entry in the symbol table. Ldlitem will fail if it finds 
no line number equal to or greater than linenum. 

The programs must be loaded with the object file access rou- 
tine library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldtbindex(3X), ldfcn(4). 
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NAME 

Idlseek, Idnlseek - seek to line number entries of a section of a 
common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int Idlseek (Idptr, sectindx) 
LDFILE *ldptr; 
unsigned short sectindx; 

int Idnlseek (Idptr, sectname) 
LDFILE *ldptr; 
char *sectname; 

DESCRIPTION 

Idlseek seeks to the line number entries of the section speci- 
fied by sectindx of the common object file currently associ- 
ated with Idptr. 

Ldnlseek seeks to the line number entries of the section speci- 
fied by sectname. 

Idlseek and Idnlseek return SUCCESS or FAILURE. Idlseek 
will fail if sectindx is greater than the number of sections in the 
object file; Idnlseek will fail if there is no section name 
corresponding with *sectname. Either function will fail if the 
specified section has no line number entries or if it cannot 
seek to the specified line number entries. 

Note that the first section has an index of one. 

The program must be loaded with the object file access rou- 
tine library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldshread(3X), ldfcn(4). 
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NAME 

Idohseek - seek to the optional file header of a common object 
file 

SYNOPSIS 

#include <stdio.h> 
#include <filehdr.h> 
#include <ldfcn.h> 

int Idohseek (Idptr) 
LDFILE *ldptr; 

DESCRIPTION 

Idohseek seeks to the optional file header of the common 
object file currently associated with Idptr. 

Idohseek returns SUCCESS or FAILURE. Idohseek will fail if 
the object file has no optional header or if it cannot seek to 
the optional header. 

The program must be loaded with the object file access rou- 
tine library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldfhread(3X), ldfcn(4). 
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NAME 

Idopen, Idaopen - open a common object file for reading 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

LDFILE *ldopen (filename, Idptr) 
char ^filename; 
LDFILE *ldptr; 

LDFILE *ldaopen (filename, oldptr) 
char ^filename; 
LDFILE *oldptr; 

DESCRIPTION 

Idopen and ldclose(3X) are designed to provide uniform 
access to both simple object files and object files that are 
members of archive files. Thus an archive of common object 
files can be processed as if it were a series of simple common 
object files. 

If Idptr has the value NULL, then Idopen will open filename 
and allocate and initialize the LDFILE structure, and return a 
pointer to the structure to the calling program. 

If Idptr is valid and if TYPE(/c/pfr) is the archive magic number, 
Idopen will reinitialize the LDFILE structure for the next 
archive member of filename . 

Idopen and ldclose{3X) are designed to work in concert. 
Ldclose will return FAILURE only when T\PE(ldptr) is the 
archive magic number and there is another file in the archive 
to be processed. Only then should Idopen be called with the 
current value of Idptr. In all other cases, in particular when- 
ever a new filename is opened, Idopen should be called with a 
NULL Idptr argument. 

The following is a prototype for the use of Idopen and 
ldclose(3X). 
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/* for each filename to be processed */ 

Idptr = NULL; 
do 

{ 

if ( (Idptr = Idopen (filename, Idptr)) ! = NULL ) 

{ 

/* check magic number */ 
/* process the file */ 

} 

} while (Idclose(ldptr) = = FAILURE ); 

If the value of oldptr is not NULL, Idaopen will open filename 
anew and allocate and initialize a new LDFILE structure, copy- 
ing the TYPE, OFFSET, and HEADER fields from oldptr. 
Ldaopen returns a pointer to the new LDFILE structure. This 
new pointer is independent of the old pointer, oldptr. The two 
pointers may be used concurrently to read separate parts of 
the object file. For example, one pointer may be used to step 
sequentially through the relocation information, while the other 
is used to read indexed symbol table entries. 

Both Idopen and Idaopen open filename for reading. Both 
functions return NULL if filename cannot be opened, or if 
memory for the LDFILE structure cannot be allocated. A suc- 
cessful open does not insure that the given file is a common 
object file or an archived object file. 

The program must be loaded with the object file access rou- 
tine library libld.a. 

SEE ALSO 

fopen(3S), ldclose(3X), ldfcn(4). 
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NAME 

Idrseek, Idnrseek - seek to relocation entries of a section of a 
common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int Idrseek (Idptr, sectindx) 
LDFILE *ldptr; 
unsigned short sectindx; 

int Idnrseek (Idptr, sectname) 
LDFILE *ldptr; 
char *sectname; 

DESCRIPTION 

Idrseek seeks to the relocation entries of the section specified 
by sectindx of the common object file currently associated 
with Idptr. 

Ldnrseek seeks to the relocation entries of the section speci- 
fied by sectname. 

Idrseek and Idnrseek return SUCCESS or FAILURE. Idrseek 
will fail if sectindx is greater than the number of sections in the 
object file; Idnrseek will fail if there is no section name 
corresponding with sectname. Either function will fail if the 
specified section has no relocation entries or if it cannot seek 
to the specified relocation entries. 

Note that the first section has an index of one. 

The program must be loaded with the object file access rou- 
tine library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldshread(3X), ldfcn(4). 
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NAME 

Idshread, Idnshread - read an indexed/named section header 
of a common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h > 

#include <scnhdr.h> 

#include <ldfcn.h> 

int Idshread (Idptr, sectindx, secthead) 
LDFILE *ldptr; 
unsigned short sectindx; 
SCNHDR * secthead; 

int Idnshread (Idptr, sectname, secthead) 
LDFILE *ldptr; 
char *sectname; 
SCNHDR *secthead; 

DESCRIPTION 

Idshread reads the section header specified by sectindx of the 
common object file currently associated with Idptr into the 
area of memory beginning at secthead. 

Ldnshread reads the section header specified by sectname 
into the area of memory beginning at secthead. 

Idshread and Idnshread return SUCCESS or FAILURE. 
Idshread will fail if sectindx is greater than the number of sec- 
tions in the object file; Idnshread will fail if there is no section 
name corresponding with sectname. Either function will fail if 
it cannot read the specified section header. 

Note that the first section header has an index of one. 

The program must be loaded with the object file access rou- 
tine library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldfcn(4). 
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NAME 

Idsseek, Idnsseek - seek to an indexed/named section of a 
common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int Idsseek (Idptr, sectindx) 
LDFILE *ldptr; 
unsigned short sectindx; 

int Idnsseek (Idptr, sectname) 
LDFILE *ldptr; 
char *sectname; 

DESCRIPTION 

Idsseek seeks to the section specified by sectindx of the com- 
mon object file currently associated with Idptr. 

Ldnsseek seeks to the section specified by sectname. 

Idsseek and Idnsseek return SUCCESS or FAILURE. Idsseek 
will fail if sectindx is greater than the number of sections in the 
object file; Idnsseek will fail if there is no section name 
corresponding with sectname. Either function will fail if there 
is no section data for the specified section or if it cannot seek 
to the specified section. 

Note that the first section has an index of one. 

The program must be loaded with the object file access rou- 
tine library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldshread(3X), ldfcn(4). 
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NAME 

Idtbindex - compute the index of a symbol table entry of a 
common object file 

SYNOPSIS 

#include <stdio.h> 
#include <filehdr.h> 
#include <syms.h> 
#include <ldfcn.h> 

long Idtbindex (Idptr) 
LDFILE *ldptr; 

DESCRIPTION 

Idtbindex returns the (long) index of the symbol table entry at 
the current position of the common object file associated with 
Idptr. 

The index returned by Idtbindex may be used in subsequent 
calls to Idtbread (3X) . However, since Idtbindex returns the 
index of the symbol table entry that begins at the current 
position of the object file, if Idtbindex is called immediately 
after a particular symbol table entry has been read, it will 
return the index of the next entry. 

Idtbindex will fail if there are no symbols in the object file, or if 
the object file is not positioned at the beginning of a symbol 
table entry. 

Note that the first symbol in the symbol table has an index of 
zero. 

The program must be loaded with the object file access rou- 
tine library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), Idtbread (3X), ldtbseek(3X), ldfcn(4). 



UP-13712 



Page 1 



LI)TBINDEX(3X) 



[This page left blank.] 



Page 2 



LDTBREAD(3X) 



NAME 

Idtbread - read an indexed symbol table entry of a common 
object file 

SYNOPSIS 

#include <stdio.h> 
#include <filehdr.h> 
#include <syms.h> 
#include <ldfcn.h> 

int Idtbread (Idptr, symindex, symbol) 
LDFILE *ldptr; 
long symindex; 
SYMENT *symbol; 

DESCRIPTION 

Idtbread reads the symbol table entry specified by symindex 
of the common object file currently associated with Idptr into 
the area of memory beginning at symbol. 

Idtbread returns SUCCESS or FAILURE. Idtbread will fail if 
symindex is greater than or equal to the number of symbols in 
the object file, or if it cannot read the specified symbol table 
entry. 

Note that the first symbol in the symbol table has an index of 
zero. 

The program must be loaded with the object file access rou- 
tine library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldtbseek(3X), ldgetname(3X), ldfcn(4). 
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NAME 

Idtbseek - seek to the symbol table of a common object file 

SYNOPSIS 

^include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int Idtbseek (Idptr) 
LDFILE *ldptr; 

DESCRIPTION 

Idtbseek seeks to the symbol table of the common object file 
currently associated with Idptr. 

Idtbseek returns SUCCESS or FAILURE. Idtbseek will fail if 
the symbol table has been stripped from the object file, or if it 
cannot seek to the symbol table. 

The program must be loaded with the object file access ou- 
tine library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldtbread(3X), ldfcn(4). 
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NAME 

logname - return login name of user 

SYNOPSIS 

char *logname( ) 

DESCRIPTION 

logname returns a pointer to the null-terminated login name; it 
extracts the LOGNAME environment variable from the user's 
environment. 

This routine is kept in /lib/libPW.a. 

FILES 

/etc/profile 

SEE ALSO 

getenv(3C), profile(4), environ(5). 

env(1), login (1) in the User's Reference Manual. 

CAVEATS 

The return values point to static data whose content is 
overwritten by each call. 

This method of determining a login name is subject to forgery. 
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NAME 

malloc, free, realloc, calloc, mallopt, mallinfo - fast main 
memory allocator 

SYNOPSIS 

#include < malloc. h> 

char *malloc (size) 
unsigned size; 

void free (ptr) 
char *ptr; 

char * realloc (ptr, size) 
char *ptr; 
unsigned size; 

char *calloc (nelem, elsize) 
unsigned nelem, elsize; 

int mallopt (cmd, value) 
int cmd, value; 

struct mallinfo mallinfo() 

DESCRIPTION 

malloc and free provide a simple general-purpose memory 
allocation package, which runs considerably faster than the 
malloc(3C) package. It is found in the library "malloc", and is 
loaded if the option "-Imalloc" is used with cc(1) or ld{1). 

malloc returns a pointer to a block of at least size bytes suit- 
ably aligned for any use. 

The argument to free is a pointer to a block previously allo- 
cated by malloc; after free is performed this space is made 
available for further allocation, and its contents have been des- 
troyed (but see mallopt below for a way to change this 
behavior). 

Undefined results will occur if the space assigned by malloc is 
overrun or if some random number is handed to free. 

Realloc changes the size of the block pointed to by ptr to size 
bytes and returns a pointer to the (possibly moved) block. 
The contents will be unchanged up to the lesser of the new 
and old sizes. 
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Calloc allocates space for an array of nelem elements of size 
elsize. The space is initialized to zeros. 

Mallopt provides for control over the allocation algorithm. The 
available values for cmd are: 

M_MXFAST Set maxfast to value. The algorithm allocates all 
blocks below the size of maxfast in large groups 
and then doles them out very quickly. The 
default value for maxfast is 24. 

M_NLBLKS Set numlblks to value. The above mentioned 
"large groups" each contain numlblks blocks. 
Numlblks must be greater than 0. The default 
value for numlblks is 100. 

M_GRAIN Set grain to value. The sizes of all blocks 
smaller than maxfast are considered to be 
rounded up to the nearest multiple of grain. 
Grain must be greater than 0. The default value 
of grain is the smallest number of bytes which 
will allow alignment of any data type. Value will 
be rounded up to a multiple of the default when 
grain is set. 

M_KEEP Preserve data in a freed block until the next 
malloc, realloc, or calloc. This option is pro- 
vided only for compatibility with the old version 
of malloc and is not recommended. 

These values are defined in the <malloc.h > header file. 

Mallopt may be called repeatedly, but may not be called after 
the first small block is allocated. 

Mallinfo provides instrumentation describing space usage. It 
returns the structure: 



struct mallinfo { 
int arena; 
int ordblks; 
int smblks; 
int hblkhd; 
int hblks; 
int usmblks; 
int fsmblks; 
int uordblks; 



/* total space in arena */ 
/* number of ordinary blocks */ 
/* number of small blocks */ 
/* space in holding block headers 
/* number of holding blocks */ 
/* space in small blocks in use */ 
/* space in free small blocks */ 
/* space in ordinary blocks in use 
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int fordblks; /* space in free ordinary blocks */ 
int keepcost; /* space penalty if keep option */ 
/* is used */ 

} 

This structure is defined in the <malloc.h > header file. 

Each of the allocation routines returns a pointer to space suit- 
ably aligned (after possible pointer coercion) for storage of 
any type of object. 

SEE ALSO 

brk(2), malloc(3C). 

DIAGNOSTICS 

malloc, realloc and calloc return a NULL pointer if there is not 
enough available memory. When realloc returns NULL, the 
block pointed to by ptr is left intact. If mallopt is called after 
any allocation or if cmd or value are invalid, non-zero is 
returned. Otherwise, it returns zero. 

WARNINGS 

This package usually uses more data space than malloc (3C). 
The code size is also bigger than malloc (3C). 
Note that unlike malloc (3C), this package does not preserve 
the contents of a block when it is freed, unless the M_KEEP 
option of mallopt is used. 

Undocumented features of malloc (3C) have not been dupli- 
cated. 
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NAME 

plot - graphics interface subroutines 

SYNOPSIS 
openpl () 

erase () 

label (s) 
char *s; 

line (x1, y1, x2, y2) 
int x1, y1, x2, y2; 

circle (x, y, r) 
int x, y, r; 

arc (x, y, xO, yO, x1, y1) 
int x, y, xO, yO, x1, y1; 

move (x, y) 
int x, y; 

cont (x, y) 
int x, y; 

point (x, y) 
int x, y; 

linemod (s) 
char *s; 

space (xO, yO, x1, y1) 
int xO, yO, x1, y1; 

closepl () 

DESCRIPTION 

These subroutines generate graphic output in a relatively 
device-independent manner. Space must be used before any 
of these functions to declare the amount of space necessary 
[see plot {4)]. Openpl must be used before any of the others 
to open the device for writing. Closepl flushes the output. 

Circle draws a circle of radius r with center at the point (x, y). 

Arc draws an arc of a circle with center at the point (x, y) 
between the points (xO, yO) and (x1, y1) . 

String arguments to label and linemod are terminated by nulls 
and do not contain new-lines. 
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See plot {4) for a description of the effect of the remaining 
functions. 

The library files listed below provide several flavors of these 
routines. 



produces output for tplot (1G) filters 

for DASI 300 

for DASI 300s 

for DASI 450 

for TEKTRONIX 4014 



FILES 

LIBDIR/libplot.a 

LIBDIR/lib300.pa 
LIBDIR/lib300.a 
LIBDIR/lib450.a 
LIBDIR/lib4014.a 
LIBDIR usually /usr/lib 

SEE ALSO 

plot(4). 

graph(lG), stat(lG), tplot(1G) in the User's Reference Manual. 
WARNINGS 

In order to compile a program containing these functions in 
file.c it is necessary to use "cc f/7e.c -Iplot". 

In order to execute it, it is necessary to use "a.out | tplot". 

The above routines use <stdio.h>, which causes them to 
increase the size of programs, not otherwise using standard 
I/O more than might be expected. 
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NAME 

regcmp, regex - compile and execute regular expression 
SYNOPSIS 

char *regcmp (string 1 [, string2, ...], (char *)0) 
char *string1, *string2, ...; 

char *regex (re, subject[, retO, ...]) 
char *re, *subject, *retO, 

extern char * lod; 

DESCRIPTION 

regcmp compiles a regular expression (consisting of the con- 
catenated arguments) and returns a pointer to the compiled 
form. Malloc(3C) is used to create space for the compiled 
form. It is the user's responsibility to free unneeded space so 
allocated. A NULL return from regcmp indicates an incorrect 
argument, regcmp (1) has been written to generally preclude 
the need for this routine at execution time. 

Regex executes a compiled pattern against the subject string. 
Additional arguments are passed to receive values back. 
Regex returns NULL on failure or a pointer to the next 
unmatched character on success. A global character pointer 

lod points to where the match began, regcmp and regex 

were mostly borrowed from the editor, ed(1); however, the 
syntax and semantics have been changed slightly. The follow- 
ing are the valid symbols and their associated meanings. 

[]*." These symbols retain their meaning in ec/(1). 

$ Matches the end of the string; \n matches a new-line. 

Within brackets the minus means through. For exam- 
ple, [a-z] is equivalent to [abed . . .xyz]. The - can 
appear as itself only if used as the first or last charac- 
ter. For example, the character class expression []-] 
matches the characters ] and -. 

+ A regular expression followed by + means one or 
more times. For example, [0-9]+ is equivalent to 
[0-9] [0-9]*. 

{m} {m,} {m,u} 

Integer values enclosed in { } indicate the number of 
times the preceding regular expression is to be 
applied. The value m is the minimum number and u 
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is a number, less than 256, which is the maximum. If 
only m is present (e.g., {m}), it indicates the exact 
number of times the regular expression is to be 
applied. The value {m,} is analogous to {m, infinity}. 
The plus ( + ) and star (*) operations are equivalent to 
{1,} and {0,} respectively. 

( . . . )$n The value of the enclosed regular expression is to be 
returned. The value will be stored in the (n+1)Xh 
argument following the subject argument. At most 
ten enclosed regular expressions are allowed. Regex 
makes its assignments unconditionally. 

(...) Parentheses are used for grouping. An operator, 
e.g., *, +, {}, can work on a single character or a 
regular expression enclosed in parentheses. For 
example, (a*(cb+)*)$0. 

By necessity, all the above defined symbols are special. They 
must, therefore, be escaped with a \ (backslash) to be used as 
themselves. 

EXAMPLES 

Example 1: 

char *cursor, *newcursor, *ptr; 

newcursor = regex((ptr = regcmp(""\n", (char *)0)), 
cursor);free(ptr); 

This example will match a leading new-line in the subject string 
pointed at by cursor. 

Example 2: 

char ret0[9]; 

char *newcursor, *name; 

name = regcmp("([A-Za-z][A-za-zO-9]{0,7})$0", (char *)0); 
newcursor = regex(name, "012Testing345", retO); 

This example will match through the string "Testing3" and will 
return the address of the character after the last matched 
character (the "4"). The string "Testing3" will be copied to the 
character array retO. 

Example 3: 

#include "file.i" 
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char *string, *newcursor; 

newcursor = regex(name, string); 

This example applies a precompiled regular expression in file.i 
[see regcmp(l)] against string. 

These routines are kept in /lib/libPW.a. 

SEE ALSO 

regcmp(1), malloc(3C). 

ed(1) in the User's Reference Manual. 

BUGS 

The user program may run out of memory if regcmp is called 
iteratively without freeing the vectors no longer required. 
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NAME 

abort - terminate Fortran program 

SYNOPSIS 

call abort ( ) 

DESCRIPTION 

abort terminates the program which calls it, closing all open 
files truncated to the current position of the file pointer. The 
abort usually results in a core dump. 

DIAGNOSTICS 

When invoked, abort prints "Fortran abort routine called" on 
the standard error output. The shell prints the message 
"abort - core dumped" if a core dump results. 

SEE ALSO 

abort (3C). 

sh(1) in the User's Reference Manual. 
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NAME 

abs, iabs, dabs, cabs, zabs - Fortran absolute value 

SYNOPSIS 

integer i1, i2 
real r1, r2 

double precision dpi, dp2 
complex cx1, cx2 
double complex dx1, dx2 

r2 = abs(r1) 

i2 = iabs(M) 
i2 = abs(i1) 

dp2 = dabs(dpl) 
dp2 = abs(dpl) 

cx2 = cabs(cxl) 
cx2 = abs(cxl) 

dx2 = zabs(dxl) 
dx2 = abs(dxl) 

DESCRIPTION 

abs is the family of absolute value functions. labs returns the 
integer absolute value of its integer argument. Dabs returns 
the double-precision absolute value of its double-precision 
argument. Cabs returns the complex absolute value of its 
complex argument. Zabs returns the double-complex abso- 
lute value of its double-complex argument. The generic form 
abs returns the type of its argument. 

SEE ALSO 

floor (3M). 
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NAME 

acos, dacos - Fortran arccosine intrinsic function 

SYNOPSIS 
real r1, r2 

double precision dpi, dp2 

r2 = acos(r1) 

dp2 = dacos(dpl) 
dp2 = acos(dpl) 

DESCRIPTION 

acos returns the real arccosine of its real argument. Dacos 
returns the double-precision arccosine of its double-precision 
argument. The generic form acos may be used with impunity 
as its argument will determine the type of the returned value. 

SEE ALSO 

trig(3M). 
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NAME 

aimag, dimag - Fortran imaginary part of complex argument 

SYNOPSIS 
real r 

complex cxr 
double precision dp 
double complex cxd 

r = aimag(cxr) 

dp = dimag(cxd) 

DESCRIPTION 

aimag returns the imaginary part of its single-precision com- 
plex argument. Dimag returns the double-precision imaginary 
part of its double-complex argument. 
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NAME 

aint, dint - Fortran integer part intrinsic function 

SYNOPSIS 
real r1, r2 

double precision dpi, dp2 

r2 = aint(r1) 

dp2 = dint(dpl) 
dp2 = aint(dp1) 

DESCRIPTION 

aint returns the truncated value of its real argument in a real. 
Dint returns the truncated value of its double-precision argu- 
ment as a double-precision value, aint may be used as a gen- 
eric function name, returning either a real or double-precision 
value depending on the type of its argument. 
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NAME 

asin, dasin - Fortran arcsine intrinsic function 

SYNOPSIS 
real r1, r2 

double precision dpi, dp2 

r2 = asin(r1) 

dp2 = dasin(dpl) 
dp2 = asin(dpl) 

DESCRIPTION 

asin returns the real arcsine of its real argument. Dasin 
returns the double-precision arcsine of its double-precision 
argument. The generic form asin may be used with impunity 
as it derives its type from that of its argument. 

SEE ALSO 

trig(3M). 
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NAME 

atan, datan - Fortran arctangent intrinsic function 

SYNOPSIS 
real r1, r2 

double precision dpi, dp2 

r2 = atan(r1) 

dp2 = datan(dpl) 
dp2 = atan(dpl) 

DESCRIPTION 

atan returns the real arctangent of its real argument. Datan 
returns the double-precision arctangent of its double-precision 
argument. The generic form atan may be used with a 
double-precision argument returning a double-precision value. 

SEE ALSO 

trig(3M). 
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NAME 

atan2, datan2 - Fortran arctangent intrinsic function 

SYNOPSIS 

real r1, r2, r3 

double precision dpi, dp2, dp 3 

r3 = atan2(r1, r2) 

dp3 = datan2(dp1, dp2) 
dp3 = atan2(dp1, dp2) 

DESCRIPTION 

atan2 returns the arctangent of arg1Jarg2 as a real value. 
Datan2 returns the double-precision arctangent of its double- 
precision arguments. The generic form atan2 may be used 
with impunity with double-precision arguments. 

SEE ALSO 

trig(3M). 
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NAME 

bool: and, or, xor, not, Ishift, rshift - Fortran Bitwise Boolean 
functions 

SYNOPSIS 

integer i, j, k 
real a, b, c 

k = and(i, j) 
c = or(a, b) 
j = xor(i, a) 
j = not(i) 
k = lshift(i, j) 
k = rshifl(i, j) 

DESCRIPTION 

The generic intrinsic Boolean functions and, or and xor return 
the value of the binary operations on their arguments. Not is 
a unary operator returning the one's complement of its argu- 
ment. Lshift and rshift return the value of the first argument 
shifted left or right, respectively, the number of times specified 
by the second (integer) argument. 

While it is recommended that Boolean functions be used only 
on integer data, these functions are generic; that is, they are 
defined for all data types as arguments and return values. 
Where required, the compiler generates appropriate type 
conversions. However, when the functions are not used with 
integer data, the results are unpredictable. 

BUGS 

The implementation of the shift functions may cause large 
shift values to deliver weird results. 

SEE ALSO 

mil(3F). 
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NAME 

conjg, dconjg - Fortran complex conjugate intrinsic function 

SYNOPSIS 

complex cx1, cx2 
double complex dx1, dx2 

cx2 = conjg(cxl) 

dx2 = dconjg(dxl) 

DESCRIPTION 

conjg returns the complex conjugate of its complex argument. 
Dconjg returns the double-complex conjugate of its double- 
complex argument. 
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NAME 

cos, dcos, ccos - Fortran cosine intrinsic function 

SYNOPSIS 
real r1, r2 

double precision dpi, dp2 
complex cx1, cx2 

r2 = cos(r1) 

dp2 = dcos(dpl) 
dp2 = cos(dpl) 

cx2 = ccos(cxl) 
cx2 = cos(cxl) 

DESCRIPTION 

cos returns the real cosine of its real argument. Dcos returns 
the double-precision cosine of its double-precision argument. 
Ccos returns the complex cosine of its complex argument. 
The generic form cos may be used with impunity as its 
returned type is determined by that of its argument. 

SEE ALSO 

trig(3M). 
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NAME 

cosh, dcosh - Fortran hyperbolic cosine intrinsic function 

SYNOPSIS 
real r1, r2 

double precision dpi, dp2 

r2 = cosh(r1) 

dp2 = dcosh(dpl) 
dp2 = cosh(dpl) 

DESCRIPTION 

cosh returns the real hyperbolic cosine of its real argument. 
Dcosh returns the double-precision hyperbolic cosine of its 
double-precision argument. The generic form cosh may be 
used to return the hyperbolic cosine in the type of its argu- 
ment. 

SEE ALSO 

sinh(3M). 
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NAME 

dim, ddim, idim - positive difference intrinsic functions 

SYNOPSIS 

integer a1, a2, a3 
a3 = idim(a1, a2) 

real a1, a2, a3 
a3 = dim(a1, a2) 

double precision a1, a2, a3 
a3 = ddim(a1, a2) 

DESCRIPTION 

These functions return: 
a1-a2 if a1 > a2 
0 if a1 < = a2 
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NAME 

dprod - double precision product intrinsic function 

SYNOPSIS 
real a1, a2 

double precision a3 

a3 = dprod(a1, a2) 
DESCRIPTION 

Dprod returns the double precision product of its real argu- 
ments. 



UP-13712 



Page 1 



DPROD(3F) 



[This page left blank.] 



Page 2 



UP-13712 



EXP(3F) 



NAME 

exp, dexp, cexp - Fortran exponential intrinsic function 

SYNOPSIS 
real r1, r2 

double precision dpi, dp2 
complex cx1, cx2 

r2 = exp(r1) 

dp2 = dexp(dpl) 
dp2 = exp(dpl) 

cx2 = cexp(cxl) 
cx2 = exp(cxl) 

DESCRIPTION 

exp returns the real exponential function e x of its real argu- 
ment. Dexp returns the double-precision exponential function 
of its double-precision argument. Cexp returns the complex 
exponential function of its complex argument. The generic 
function exp becomes a call to dexp or cexp as required, 
depending on the type of its argument. 

SEE ALSO 

exp(3M). 
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NAME 

ftype: int, ifix, idint, real, float, sngl, dble, cmplx, dcmplx, ichar, 
char - explicit Fortran type conversion 

SYNOPSIS 
integer i, j 
real r, s 

double precision dp, dq 
complex cx 
double complex dcx 
character* 7 ch 
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dcx = dcmplx(cx) 

i = ichar(ch) 
ch = char(i) 

DESCRIPTION 

These functions perform conversion from one data type to 
another. 

The function int converts to integer form its real, double preci- 
sion, complex, or double complex argument. If the argument 
is real or double precision, int returns the integer whose mag- 
nitude is the largest integer that does not exceed the magni- 
tude of the argument and whose sign is the same as the sign 
of the argument (i.e. truncation). For complex types, the 
above rule is applied to the real part, ifix and idint convert 
only real and double precision arguments respectively. 

The function real converts to real form an integer, double pre- 
cision, complex, or double complex argument. If the argu- 
ment is double precision or double complex, as much preci- 
sion is kept as is possible. If the argument is one of the com- 
plex types, the real part is returned, float and sngl convert 
only integer and double precision arguments respectively. 

The function dble converts any integer, real, complex, or dou- 
ble complex argument to double precision form. If the argu- 
ment is of a complex type, the real part is returned. 

The function cmplx converts its integer, real, double precision, 
or double complex argument(s) to complex form. 

The function dcmplx converts to double complex form its 
integer, real, double precision, or complex argument (s). 

Either one or two arguments may be supplied to cmplx and 
dcmplx . If there is only one argument, it is taken as the real 
part of the complex type and an imaginary part of zero is sup- 
plied. If two arguments are supplied, the first is taken as the 
real part and the second as the imaginary part. 

The function ichar converts from a character to an integer 
depending on the character's position in the collating 
sequence. 

The function char returns the character in the /th position in 
the processor collating sequence where / is the supplied argu- 
ment. 
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For a processor capable of representing n characters, 

ichar(char(i)) = i for 0 < = i < n, and 

char(ichar(ch)) = ch for any representable character ch. 
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NAME 

getarg - return Fortran command-line argument 

SYNOPSIS 

character*N c 
integer i 

call getarg(i, c) 

DESCRIPTION 

getarg returns the /-th command-line argument of the current 
process. Thus, if a program were invoked via 

foo arg1 arg2 arg3 

getarg(2, c) would return the string "arg2" in the character 
variable c. 

SEE ALSO 

getopt(3C). 
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NAME 

getenv - return Fortran environment variable 

SYNOPSIS 

character*N c 

call getenv("VARIABLE_NAME", c) 
DESCRIPTION 

getenv returns the character-string value of the environment 
variable represented by its first argument into the character 
variable of its second argument. If no such environment vari- 
able exists, all blanks will be returned. 

SEE ALSO 

getenv(3C), environ(5). 
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NAME 

iargc - return the number of command line arguments 

SYNOPSIS 
integer i 

i = iargc( ) 
DESCRIPTION 

The iargc function returns the number of command line argu- 
ments passed to the program. Thus, if a program were 
invoked via 

too arg1 arg2 arg3 

iargc( ) would return 3. 

SEE ALSO 

getarg(3F). 
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NAME 

index - return location of Fortran substring 

SYNOPSIS 

character*N1 ch1 
character*N2 ch2 
integer i 

i = index(ch1, ch2) 
DESCRIPTION 

index returns the location of substring ch2 in string ch1. The 
value returned is the position at which substring ch2 starts, or 
0 if it is not present in string ch1 . If N2 is greater than N1, a 
zero is returned. 
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NAME 

len - return length of Fortran string 

SYNOPSIS 

character*N ch 
integer i 

i = len(ch) 

DESCRIPTION 

len returns the length of string ch. 
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NAME 

log, alog, dlog, clog - Fortran natural logarithm intrinsic func- 
tion 

SYNOPSIS 
real r1, r2 

double precision dpi, dp2 
complex cx1, cx2 

r2 = alog(r1) 
r2 = log(r1) 

dp2 = dlog(dpl) 
dp2 = log(dpl) 

cx2 = clog(cxl) 
cx2 = log(cxl) 

DESCRIPTION 

Alog returns the real natural logarithm of its real argument. 
Dlog returns the double-precision natural logarithm of its 
double-precision argument. Clog returns the complex loga- 
rithm of its complex argument. The generic function log 
becomes a call to alog, dlog, or clog depending on the type 
of its argument. 

SEE ALSO 

exp(3M). 
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NAME 

Iog10, aloglO, dloglO - Fortran common logarithm intrinsic 
function 

SYNOPSIS 
real M, r2 

double precision dpi, dp2 

r2 = alog10(r1) 
r2 = Iog10(r1) 

dp2 = dlog10(dp1) 
dp2 = Iog10(dp1) 

DESCRIPTION 

AloglO returns the real common logarithm of its real argu- 
ment. DloglO returns the double-precision common logarithm 
of its double-precision argument. The generic function Iog10 
becomes a call to aloglO or dloglO depending on the type of 
its argument. 

SEE ALSO 

exp(3M). 
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NAME 

max, maxO, amaxO, max1, amaxl, dmaxl - Fortran maximum- 
value functions 

SYNOPSIS 

integer i, j, k, I 
real a, b, c, d 

double precision dpi, dp2, dp3 



1 = 


max(i, j, k) 


c = 


max(a, b) 


dp = 


= max(a, b, c) 


k = 


maxO(i, j) 


a = 


amaxO(i, j, k) 




max1(a, b) 


d = 


amaxl (a, b, c) 


dp3 


= dmaxl (dpi, dp2) 



DESCRIPTION 

The maximum-value functions return the largest of their argu- 
ments (of which there may be any number), max is the gen- 
eric form which can be used for all data types and takes its 
return type from that of its arguments (which must all be of 
the same type). maxO returns the integer form of the max- 
imum value of its integer arguments; amaxO, the real form of 
its integer arguments; max1 , the integer form of its real argu- 
ments; amaxl , the real form of its real arguments; and dmaxl , 
the double-precision form of its double-precision arguments. 

SEE ALSO 

min(3F). 
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NAME 

mclock - return Fortran time accounting 

SYNOPSIS 
integer i 

i = mclock( ) 

DESCRIPTION 

mclock returns time accounting information about the current 
process and its child processes. The value returned is the sum 
of the current process's user time and the user and system 
times of all child processes. 

SEE ALSO 

times(2), clock(3C), system(3F). 
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NAME 

mil: ior, iand, not, ieor, ishft, ishftc, ibits, btest, ibset, ibclr, 
mvbits - Fortran Military Standard functions 

SYNOPSIS 

integer i, k, I, m, n, len 
logical b 

i = ior(m, n) 

i = iand(m, n) 

i = not(m) 

i = ieor(m, n) 

i = ishft(m, k) 

i = ishftc(m, k, len) 

i = ibits(m, k, len) 

b = btest(n, k) 

i = ibset(n, k) 

i = ibclr(n, k) 

call mvbits(m, k, len, n, I) 

DESCRIPTION 

mil is the general name for the bit field manipulation intrinsic 
functions and subroutines from the Fortran Military Standard 
(MIL-STD-1753). ior, iand, not, ieor - return the same results 
as and, or, not, xor as defined in doo/(3F) . 

ishft, ishftc - m specifies the integer to be shifted, k specifies 
the shift count, k > 0 indicates a left shift, k = 0 indicates 
no shift, k < 0 indicates a right shift. In ishft, zeros are 
shifted in. In ishftc, the rightmost len bits are shifted circularly 
k bits. If k is greater than the machine word-size, ishftc will 
not shift 

Bit fields are numbered from right to left and the rightmost bit 
position is zero. The length of the len field must be greater 
than zero. 

ibits - extract a subfield of len bits from m starting with bit 
position k and extending left for len bits. The result field is 
right justified and the remaining bits are set to zero. 

btest - The kth bit of argument n is tested. The value of the 
function is .TRUE, if the bit is a 1 and .FALSE, if the bit is 0. 

ibset - the result is the value of n with the kth bit set to 1 . 
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ibclr - the result is the value of n with the kth bit set to 0. 

mvbits - len bits are moved beginning at position k of argu- 
ment m to position I of argument n. 

SEE ALSO 

bool(3F). 
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NAME 

min, minO, aminO, mini, aminl, dminl - Fortran minimum- 
value functions 

SYNOPSIS 

integer i, j, k, I 
real a, b, c, d 

double precision dpi, dp2, dp3 

I = min(i, j, k) 

c = min(a, b) 

dp = min(a, b, c) 

k = minO(i, j) 

a = aminO(i, j, k) 

i = mini (a, b) 

d = aminl (a, b, c) 

dp3 = dminl (dpi, dp2) 

DESCRIPTION 

The minimum-value functions return the minimum of their 
arguments (of which there may be any number), min is the 
generic form which can be used for all data types and takes 
its return type from that of its arguments (which must all be of 
the same type). minO returns the integer form of the 
minimum value of its integer arguments; aminO, the real form 
of its integer arguments; mini, the integer form of its real 
arguments; aminl, the real form of its real arguments; and 
dminl , the double-precision form of its double-precision argu- 
ments. 

SEE ALSO 

max(3F). 
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NAME 

mod, amod, dmod - Fortran remaindering intrinsic functions 

SYNOPSIS 

integer i, j, k 
real r1, r2, r3 

double precision dpi, dp2, dp3 

k = mod(i, j) 

r3 = amod(r1, r2) 
r3 = mod(M, r2) 

dp3 = dmod(dp1, dp2) 
dp3 = mod(dp1, dp2) 

DESCRIPTION 

mod returns the integer remainder of its first argument 
divided by its second argument. Amod and dmod return, 
respectively, the real and double-precision whole number 
remainder of the integer division of their two arguments. The 
generic version mod will return the data type of its arguments. 
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NAME 

rand, irand, srand - random number generator 

SYNOPSIS 

integer iseed, i, irand 
double precision x, rand 

call srand(iseed) 
i = irand( ) 
x = rand( ) 
DESCRIPTION 

Irand generates successive pseudo-random integers in the 
range from 0 to 2**15-1. rand generates pseudo-random 
numbers distributed in [0, 1.0]. Srand uses its integer argu- 
ment to re-initialize the seed for successive invocations of 
irand and rand. 

SEE ALSO 

rand(3C). 
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NAME 

round: anint, dnint, nint, idnint - Fortran nearest integer func- 
tions 

SYNOPSIS 
integer i 
real r1, r2 

double precision dpi, dp2 

r2 = anint(rl) 
i = nint(M) 

dp2 = anint(dpl) 
dp2 = dnint(dpl) 

i = nint(dpl) 
i = idnint(dpl) 

DESCRIPTION 

Anint returns the nearest whole real number to its real argu- 
ment (i.e., int(a + 0.5) if a > = 0, int(a-0.5) otherwise). Dnint 
does the same for its double-precision argument. Nint returns 
the nearest integer to its real argument. Idnint is the double- 
precision version. Anint is the generic form of anint and dnint, 
performing the same operation and returning the data type of 
its argument. Nint is also the generic form of idnint. 
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NAME 

sign, isign, dsign - Fortran transfer-of-sign intrinsic function 

SYNOPSIS 

integer i, j, k 
real r1, r2, r3 

double precision dpi, dp2, dp3 

k = isign(i, j) 
k = sign(i, j) 

r3 = sign(r1, r2) 

dp3 = dsign(dp1, dp2) 
dp3 = sign(dp1, dp2) 

DESCRIPTION 

Isign returns the magnitude of its first argument with the sign 
of its second argument, sign and dsign are its real and 
double-precision counterparts, respectively. The generic ver- 
sion is sign and will devolve to the appropriate type depend- 
ing on its arguments. 
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NAME 

signal - specify Fortran action on receipt of a system signal 

SYNOPSIS 

integer i, intfc 
external intfc 

call signal(i, intfc) 

DESCRIPTION 

The argument i specifies the signal to be caught, signal 
allows a process to specify a function to be invoked upon 
receipt of a specific signal. The first argument specifies which 
fault or exception. The second argument specifies the func- 
tion to be invoked. 

NOTE: The interrupt processing function, intfc, does not take 
an argument. 

SEE ALSO 

kill(2), signal(2). 
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NAME 

sin, dsin, csin - Fortran sine intrinsic function 

SYNOPSIS 
real r1, r2 

double precision dpi, dp2 
complex cx1, cx2 

r2 = sin(r1) 

dp2 = dsin(dpl) 
dp2 = sin(dpl) 

cx2 = csin(cxl) 
cx2 = sin(cxl) 

DESCRIPTION 

sin returns the real sine of its real argument. Dsin returns the 
double-precision sine of its double-precision argument. Csin 
returns the complex sine of its complex argument. The gen- 
eric sin function becomes dsin or csin as required by argu- 
ment type. 

SEE ALSO 

trig(3M). 
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NAME 

sinh, dsinh - Fortran hyperbolic sine intrinsic function 

SYNOPSIS 
real r1, r2 

double precision dpi, dp2 

r2 = sinh(r1) 

dp2 = dsinh(dpl) 
dp2 = sinh(dpl) 

DESCRIPTION 

sinh returns the real hyperbolic sine of its real argument. 
Dsinh returns the double-precision hyperbolic sine of its 
double-precision argument. The generic form sinh may be 
used to return a double-precision value when given a double- 
precision argument. 

SEE ALSO 

sinh(3M). 
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NAME 

sqrt, dsqrt, csqrt - Fortran square root intrinsic function 

SYNOPSIS 
real r1, r2 

double precision dpi, dp2 
complex cx1, cx2 

r2 = sqrt(r1) 

dp2 = dsqrt(dpl) 
dp2 = sqrt(dpl) 

cx2 = csqrt(cxl) 
cx2 = sqrt(cxl) 

DESCRIPTION 

sqrt returns the real square root of its real argument. Dsqrt 
returns the double-precision square root of its double- 
precision argument. Csqrt returns the complex square root of 
its complex argument, sqrt, the generic form, will become 
dsqrt or csqrt as required by its argument type. 

SEE ALSO 

exp(3M). 



UP-13712 



Page 1 



SQRT(3F) 



[This page left blank.] 



Page 2 



UP-13712 



STRCMP(3F) 



NAME 

strcmp: Ige, Igt, He, lit - string comparison intrinsic functions 

SYNOPSIS 

character*N a1, a2 
logical I 

I = Ige(a1, a2) 

I = Igt(a1, a2) 

I = Ile(a1, a2) 

I = Ilt(a1, a2) 

DESCRIPTION 

These functions return .TRUE, if the inequality holds and 
.FALSE, otherwise. 
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NAME 

system - issue a shell command from Fortran 

SYNOPSIS 

character*N c 

call system(c) 

DESCRIPTION 

system causes its character argument to be given to s/i(1) as 
input, as if the string had been typed at a terminal. The 
current process waits until the shell has completed. 

SEE ALSO 

exec (2), system (3S). 

sh(1) in the User's Reference Manual. 
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NAME 

tan, dtan - Fortran tangent intrinsic function 

SYNOPSIS 
real r1, r2 

double precision dpi, dp2 

r2 = tan(r1) 

dp2 = dtan(dpl) 
dp2 = tan(dpl) 

DESCRIPTION 

tan returns the real tangent of its real argument. Dtan returns 
the double-precision tangent of its double-precision argument. 
The generic tan function becomes dtan as required with a 
double-precision argument. 

SEE ALSO 

trig(3M). 
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NAME 

tanh, dtanh - Fortran hyperbolic tangent intrinsic function 

SYNOPSIS 
real r1, r2 

double precision dpi, dp2 

r2 = tanh(M) 

dp2 = dtanh(dpl) 
dp2 = tanh(dpl) 

DESCRIPTION 

tanh returns the real hyperbolic tangent of its real argument. 
Dtanh returns the double-precision hyperbolic tangent of its 
double-precision argument. The generic form tanh may be 
used to return a double-precision value given a double- 
precision argument. 

SEE ALSO 

sinh(3M). 
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